changeset 98955:696800e083e7

New file, with some wisdom from emacs-devel.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/admin/notes/documentation	Tue Oct 21 03:22:25 2008 +0000
@@ -0,0 +1,76 @@
+-*- outline -*-
+
+Some documentation tips culled from emacs-devel postings.
+
+
+** Manual indices
+
+http://lists.gnu.org/archive/html/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 if 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
+
+http://lists.gnu.org/archive/html/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
+
+http://lists.gnu.org/archive/html/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.