diff --git a/lib/linguist/languages.yml b/lib/linguist/languages.yml
index b0ea6ff5..bd582215 100755
--- a/lib/linguist/languages.yml
+++ b/lib/linguist/languages.yml
@@ -2,7 +2,8 @@
 #
 # type              - Either data, programming, markup, prose, or nil
 # aliases           - An Array of additional aliases (implicitly
-#                     includes name.downcase)
+#                     includes the lowercase name with spaces replaced
+#                     by dashes)
 # ace_mode          - A String name of the Ace Mode used for highlighting whenever
 #                     a file is edited. This must match one of the filenames in http://git.io/3XO_Cg.
 #                     Use "text" if a mode does not exist.