-*- outline -*- Some documentation tips culled from emacs-devel postings. ** Manual indices https://lists.gnu.org/r/emacs-devel/2008-10/msg00400.html For example, this text: @vindex x-gtk-show-hidden-files @vindex x-gtk-file-dialog-help-text When Emacs is compiled with GTK+ support, it uses the GTK+ ``file chooser'' dialog. Emacs adds an additional toggle button to this dialog, which you can use to enable or disable the display of hidden files (files starting with a dot) in that dialog. If you want this toggle to be activated by default, change the variable @code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds help text to the GTK+ file chooser dialog; to disable this help text, change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. has index entries for the variables it describes, which is good, but what if a user looks for this information without knowing the names of these variables? For those, I added these two concept index entries: @cindex hidden files, in GTK+ file chooser @cindex help text, in GTK+ file chooser Thus, if a user types "i hidden files TAB" in Info, she will see the first entry, and so if she types "i file chooser RET". See why it is better? The way to come up with useful index entries is to put yourself in the shoes of someone who looks for the information, and think about words and phrases you'd use to find it. One other rule for good indexing is not to have several index entries that begin with the same substring and point to the same page or screenful (i.e. to places that are close to one another). Here's a fictitious example of such redundant entries: @cindex foobar, how to use @cindex foobar rules Either leave only one of these, e.g. just "@cindex foobar", or combine them into a single entry, e.g.: @cindex foobar, rules and usage ** Point is a proper name https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html In Emacs tradition, we treat "point" as a proper name when it refers to the current editing location. It should not have an article. Thus, it is incorrect to write, "The point does not move". It should be, "Point does not move". If you see "the point" anywhere in Emacs documentation or comments, referring to point, please fix it. ** Don't use passive verbs https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html Documentation is clearer if it avoids the passive voice whenever possible. For example, rather than saying "Point does not move", say "This does not move point". If you come across passive verbs in Emacs documentation or comments, please see if it is possible to make the text shorter and clearer using the active voice. Usually that does make an improvement. The explicit subject required by the active voice often provides important information which makes the text clearer, too. ** Antinews nodes *** Why Antinews is useful https://lists.gnu.org/r/emacs-devel/2008-11/msg00893.html The usefulness of Antinews is to help people who buy the printed manual and are still using the previous Emacs version. That's why we focus on the (eliminated) behavior of the old version rather than on the new features. Of course, we try to make it amusing as well. *** Don't mention in Antinews too many features absent in old versions https://lists.gnu.org/r/emacs-devel/2008-11/msg01054.html Since the purpose of Antinews is to help people use the previous Emacs version, there is usually no need to mention features that are simply absent in that version. That situation will be clear enough to users without help from the manual. For instance, this @item Emacs can no longer be started as a daemon. We decided that having an Emacs sitting silently in the background with no visual manifestation anywhere in sight is too confusing. may not need mentioning, because --daemon will give an error message saying it's not implemented, and other cases aren't affected. The kind of change for which the user really needs help from Antinews is where a feature works _differently_ in the previous version. In those cases, the user might have trouble figuring out how to use the old version without some sort of help. ** To indicate possession, write Emacs's rather than Emacs'. https://lists.gnu.org/r/emacs-devel/2012-02/msg00649.html ** etc/NEWS style rules Any change that matters to end-users should have an entry in etc/NEWS. This is not intended as reference of design decisions or interfaces. *** Each NEWS entry starts with a heading that summarizes the entry. It takes just one line, and will finish with a period. Section headings, which are one level up from entry headings, are not full sentences. First-level headings are broad categories, and the other section headings are the names of Emacs features. Don't use Lisp symbols for section headings. E.g. "Random mode" not "'random-mode'". *** All new, changed or obsoleted user options and commands are documented. Document the default value or the argument list, respectively. If a user option or command is obsoleted or changes the default value / argument list, document how to keep the previous behavior. Document further new, changed or obsoleted variables and functions, if they are relevant for package authors. *** Lisp symbols, Lisp forms and and key sequences are quoted 'like-this'. This results in clickable Lisp symbols when the NEWS file is visited via 'view-emacs-news' ('C-h n'). Also single key names or keywords must follow this rule, like 'TAB' or ':type'. Exception: the symbols t and nil are not quoted. Arguments of a function are written in capital letters LIKE-THIS, and they are not quoted. If Lisp forms are written in a line of its own, they are not quoted. Separate these lines from the previous and following text by an empty line. Indent them with a width of 4 spaces. *** File names, buffer names, process names are strings. Quote them with quotation marks "like this". Exception: Lisp file names like subr.el, which are not quoted. *** External program names are quoted with quotation marks like "this". *** Manuals (Info pages) are referenced like "(elisp) Documentation Tips". *** Prior pushing your changes, check the result. Call 'emacs-news-view-mode'. Lisp symbols and Info manual links shall be decorated, and clicking on them shall lead to the respective Help buffer or Info node.