# HG changeset patch
# User Richard M. Stallman <rms@gnu.org>
# Date 1005618053 0
# Node ID fb31125d0d7be45a8cef2980d333cd733c7d8d5b
# Parent  57ff4380e1fe6ac608cb08991822ecbd88f56441
Say what questions first line of doc string should answer.

diff -r 57ff4380e1fe -r fb31125d0d7b lispref/tips.texi
--- a/lispref/tips.texi	Tue Nov 13 02:20:08 2001 +0000
+++ b/lispref/tips.texi	Tue Nov 13 02:20:53 2001 +0000
@@ -489,9 +489,13 @@
 stand on their own, the result looks bad.  In particular, start the
 first line with a capital letter and end with a period.
 
-The documentation string is not limited to one line; use as many lines
-as you need to explain the details of how to use the function or
-variable.  Please use complete sentences in the additional lines.
+For a function, the first line should briefly answer the question,
+``What does this function do?''  For a variable, the first line should
+briefly answer the question, ``What does this value mean?''
+
+Don't limit the documentation string to one line; use as many lines as
+you need to explain the details of how to use the function or
+variable.  Please use complete sentences for the rest of the text too.
 
 @item
 For consistency, phrase the verb in the first sentence of a function's