| 1 | -*- outline -*- |
| 2 | |
| 3 | Some documentation tips culled from emacs-devel postings. |
| 4 | |
| 5 | |
| 6 | ** Manual indices |
| 7 | |
| 8 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html |
| 9 | |
| 10 | For example, this text: |
| 11 | |
| 12 | @vindex x-gtk-show-hidden-files |
| 13 | @vindex x-gtk-file-dialog-help-text |
| 14 | When Emacs is compiled with GTK+ support, it uses the GTK+ ``file |
| 15 | chooser'' dialog. Emacs adds an additional toggle button to this |
| 16 | dialog, which you can use to enable or disable the display of hidden |
| 17 | files (files starting with a dot) in that dialog. If you want this |
| 18 | toggle to be activated by default, change the variable |
| 19 | @code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds |
| 20 | help text to the GTK+ file chooser dialog; to disable this help text, |
| 21 | change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. |
| 22 | |
| 23 | has index entries for the variables it describes, which is good, but |
| 24 | what if a user looks for this information without knowing the names of |
| 25 | these variables? For those, I added these two concept index entries: |
| 26 | |
| 27 | @cindex hidden files, in GTK+ file chooser |
| 28 | @cindex help text, in GTK+ file chooser |
| 29 | |
| 30 | Thus, if a user types "i hidden files TAB" in Info, she will see the |
| 31 | first entry, and so if she types "i file chooser RET". See why it is |
| 32 | better? |
| 33 | |
| 34 | The way to come up with useful index entries is to put yourself in the |
| 35 | shoes of someone who looks for the information, and think about words |
| 36 | and phrases you'd use to find it. |
| 37 | |
| 38 | One other rule for good indexing is not to have several index entries |
| 39 | that begin with the same substring and point to the same page or |
| 40 | screenful (i.e. to places that are close to one another). Here's a |
| 41 | fictitious example of such redundant entries: |
| 42 | |
| 43 | @cindex foobar, how to use |
| 44 | @cindex foobar rules |
| 45 | |
| 46 | Either leave only one of these, e.g. just "@cindex foobar", or |
| 47 | combine them into a single entry, e.g.: |
| 48 | |
| 49 | @cindex foobar, rules and usage |
| 50 | |
| 51 | |
| 52 | ** Point is a proper name |
| 53 | |
| 54 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html |
| 55 | |
| 56 | In Emacs tradition, we treat "point" as a proper name when it refers |
| 57 | to the current editing location. It should not have an article. |
| 58 | |
| 59 | Thus, it is incorrect to write, "The point does not move". It should |
| 60 | be, "Point does not move". |
| 61 | |
| 62 | If you see "the point" anywhere in Emacs documentation or comments, |
| 63 | referring to point, please fix it. |
| 64 | |
| 65 | |
| 66 | ** Don't use passive verbs |
| 67 | |
| 68 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html |
| 69 | |
| 70 | Documentation is clearer if it avoids the passive voice whenever |
| 71 | possible. For example, rather than saying "Point does not move", say |
| 72 | "This does not move point". If you come across passive verbs in Emacs |
| 73 | documentation or comments, please see if it is possible to make the |
| 74 | text shorter and clearer using the active voice. Usually that does |
| 75 | make an improvement. The explicit subject required by the active voice |
| 76 | often provides important information which makes the text clearer, too. |
| 77 | |
| 78 | |
| 79 | ** Antinews nodes |
| 80 | |
| 81 | *** Why Antinews is useful |
| 82 | |
| 83 | http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00893.html |
| 84 | |
| 85 | The usefulness of Antinews is to help people who buy the printed |
| 86 | manual and are still using the previous Emacs version. That's why we |
| 87 | focus on the (eliminated) behavior of the old version rather than on |
| 88 | the new features. |
| 89 | |
| 90 | Of course, we try to make it amusing as well. |
| 91 | |
| 92 | *** Don't mention in Antinews too many features absent in old versions |
| 93 | |
| 94 | http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg01054.html |
| 95 | |
| 96 | Since the purpose of Antinews is to help people use the previous Emacs |
| 97 | version, there is usually no need to mention features that are simply |
| 98 | absent in that version. That situation will be clear enough to users |
| 99 | without help from the manual. |
| 100 | |
| 101 | For instance, this |
| 102 | |
| 103 | @item |
| 104 | Emacs can no longer be started as a daemon. We decided that having an |
| 105 | Emacs sitting silently in the background with no visual manifestation |
| 106 | anywhere in sight is too confusing. |
| 107 | |
| 108 | may not need mentioning, because --daemon will give an error message |
| 109 | saying it's not implemented, and other cases aren't affected. |
| 110 | |
| 111 | The kind of change for which the user really needs help from Antinews |
| 112 | is where a feature works _differently_ in the previous version. |
| 113 | In those cases, the user might have trouble figuring out how to use |
| 114 | the old version without some sort of help. |
| 115 | |
| 116 | ** To indicate possession, write Emacs's rather than Emacs'. |
| 117 | http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00649.html |