-# Although most aliases will contain only a few options, a number
-# of settings that are commonly used appear below:
+# $ drush --root=/path/to/drupal --uri=http://example.com status
+#
+# See "Additional Site Alias Options" below for more information.
+
+# Converting Legacy Alias Files
+#
+# To convert legacy alias (*.aliases.drushrc.php) to yml, run the
+# site:alias-convert command.
+
+# Altering aliases:
+#
+# See examples/Commands/SiteAliasAlterCommands.php for an example.
+
+# Environment variables:
+#
+# It is no longer possible to set environment variables from within an alias.
+# This is a planned feature.
+
+# Additional Site Alias Options
+#
+# Aliases are commonly used to define short names for
+# local or remote Drupal installations; however, an alias
+# is really nothing more than a collection of options.