-# Snippet definitions are put in plain text files. They are arranged\r
-# by sub-directories, and the snippet tables are named after these\r
-# directories.\r
+** Basic organization\r
+\r
+Snippet definitions are stored in plain text files. They are arranged by\r
+sub-directories. The directories name snippet tables, which in turn name\r
+Emacs major names. For example, snippets for =c-mode= are put in the\r
+``c-mode`` sub-directory while\r
+\r
+** The =.yas.parents= file\r
+\r
+It's very useful to have certain modes share snippets between themselves. To do\r
+this, choose a mode subdirectory and place a =.yas-parents= containing a\r
+whitespace-separated list of other mode names. When you reload those modes\r
+become parents of the original mode.\r