svn commit: r42006 - head/en_US.ISO8859-1/books/fdp-primer/writing-style

[Warren Block]

Author: wblock
Date: Sun Jun 23 20:14:59 2013
New Revision: 42006
URL: http://svnweb.freebsd.org/changeset/doc/42006

Log:
  Add a tip about examples.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Sun Jun 23 19:45:12 2013	(r42005)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Sun Jun 23 20:14:59 2013	(r42006)
@@ -71,6 +71,15 @@
 	rather than <quote>you can copy the file to
 	  <filename>/tmp</filename></quote>.</para>
 
+      <para>Give clear, correct examples.  A trivial example is better
+	than no example, but a good example is better yet.  Do not
+	give bad examples, identifiable by apologies or sentences like
+	<quote>but really it should never be done that way</quote>.
+	Bad examples are worse than no examples.  Give good examples,
+	because <emphasis>even when warned not to use the example
+	  as shown</emphasis>, the reader will usually just use the
+	example as shown.</para>
+
       <para>Avoid <emphasis>weasel words</emphasis> like
 	<quote>should</quote>, <quote>might</quote>,
 	<quote>try</quote>, or <quote>could</quote>.  These words
@@ -89,7 +98,8 @@
 	skill level.  Tell them what they need to know.  Give links to
 	other documents to provide background information without
 	having to recreate it.  Put yourself in the reader's place,
-	and answer the questions they will ask.</para>
+	anticipate the questions they will ask, and answer
+	them.</para>
     </sect2>
 
     <sect2 id="writing-style-be-concise">