--- a/doc/interpreter/contrib.txi	Thu Jun 02 09:06:43 2016 -0700
+++ b/doc/interpreter/contrib.txi	Thu Jun 02 09:50:29 2016 -0700
@@ -297,7 +297,7 @@
 Here, putting spaces after @code{sin}, @code{cos} would result in a
 parse error.
 
-For indexing expressions, do @emph{not} put a space after the
+For indexing expressions, do @strong{not} put a space after the
 identifier (this differentiates indexing and function calls nicely).
 The space after a comma is not necessary if index expressions are simple,
 i.e., you may write
@@ -337,8 +337,8 @@
 Always use a specific end-of-block statement (like @code{endif},
 @code{endswitch}) rather than the generic @code{end}.
 
-Enclose the @code{if}, @code{while}, @code{until}, and @code{switch}
-conditions in parentheses, as in C:
+Enclose the condition of an @code{if}, @code{while}, @code{until}, or
+@code{switch} statement in parentheses, as in C:
 
 @example
 @group
@@ -349,8 +349,8 @@
 @end example
 
 @noindent
-Do not do this, however, with the iteration counter portion of a
-@code{for} statement.  Write:
+Do not do this, however, with the iteration counter portion of a @code{for}
+statement.  Write:
 
 @example
 @group
@@ -362,11 +362,14 @@
 
 The Octave operator @samp{!} should be used for logical negation, rather than
 @samp{~}.  The negation operator is written with a space between the operator
-and its target, e.g., @code{! A}.  Comments should begin with the @samp{#}
-character, rather than @samp{%}.
+and its target, e.g., @code{! A}.
 
-Any Built-In Self Tests or demos using the @code{%!test} or @code{%!demo}
-syntax should begin two lines after the @code{endfunction} keyword.
+Comments should begin with the @samp{#} character, rather than @samp{%}.
+@xref{Comment Tips}.
+
+Any demos or Built-In Self Tests (BIST) using the @code{%!demo} or
+@code{%!test} syntax should begin two lines after the @code{endfunction}
+keyword.  Demo blocks should be listed before test blocks.
 
 @node C++ Sources
 @section C++ Sources

--- a/doc/interpreter/tips.txi	Thu Jun 02 09:06:43 2016 -0700
+++ b/doc/interpreter/tips.txi	Thu Jun 02 09:50:29 2016 -0700
@@ -63,9 +63,13 @@
 
 @item
 When you encounter an error condition, call the function @code{error}
-(or @code{usage}).  The @code{error} and @code{usage} functions do not
-return.
-@xref{Errors}.
+(or @code{print_usage}).  The @code{error} and @code{print_usage} functions
+do not return.  @xref{Errors}.  It is customary to prefix the error message
+with the name of the function that generated it.  For example,
+
+@example
+error ("my_cool_function: input A must be a matrix");
+@end example
 
 @item
 Please put a copyright notice on the file if you give copies to anyone.
@@ -82,18 +86,32 @@
 
 @table @samp
 @item #
-Comments that start with a single sharp-sign, @samp{#}, should all be
-aligned to the same column on the right of the source code.  Such
-comments usually explain how the code on the same line does its job.  In
+Comments that start with a single sharp-sign, @samp{#}, are used to explain
+the code on the same line as the comment itself.  These comments should
+all be aligned to the same column to the right of the source code.  In
 the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment})
 command automatically inserts such a @samp{#} in the right place, or
-aligns such a comment if it is already present.
+aligns such a comment if it is already present.  Example:
+
+@example
+@var{C} = 2 * pi * r;    # formula for circumference of a circle
+@end example
 
 @item ##
-Comments that start with a double sharp-sign, @samp{##}, should be aligned to
+Comments that start with a double sharp-sign, @samp{##}, are stand-alone
+comments that occupy an entire line.  These comments should be aligned to
 the same level of indentation as the code.  Such comments usually
 describe the purpose of the following lines or the state of the program
-at that point.
+at that point.  Example:
+
+@example
+@group
+## Calculate area and volume of a sphere
+@var{A} = 4 * pi * r^2;
+@var{V} = 4/3 * pi * r^3;
+@end group
+@end example
+
 @end table
 
 @noindent