--- a/doc/interpreter/tips.txi	Sun May 10 16:07:41 2015 -0700
+++ b/doc/interpreter/tips.txi	Sun May 10 21:35:59 2015 -0700
@@ -242,12 +242,17 @@
 a documentation string.
 
 @item
-The first line of the documentation string should consist of one or two
-complete sentences that stand on their own as a summary.
+The first line of the documentation string should consist of a summary of
+the function.
+
+Subsequent lines may expand the general nature of the function.
 
-The documentation string can have additional lines that expand on the
-details of how to use the function or variable.  The additional lines
-should also be made up of complete sentences.
+After the introduction there should be paragraphs describing the meaning
+and usage of each input, followed by the meaning and usage of each output.
+
+Finally, there may be more general information such as notes about the
+algorithm used, references to scientific papers, notes about any
+incompatibilities with @sc{matlab}, etc.
 
 @item
 For consistency, phrase the verb in the first sentence of a