From owner-svn-doc-all@FreeBSD.ORG  Sun Jun 23 20:14:59 2013
Return-Path: <owner-svn-doc-all@FreeBSD.ORG>
Delivered-To: svn-doc-all@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
 by hub.freebsd.org (Postfix) with ESMTP id A329A58D;
 Sun, 23 Jun 2013 20:14:59 +0000 (UTC)
 (envelope-from wblock@FreeBSD.org)
Received: from svn.freebsd.org (svn.freebsd.org
 [IPv6:2001:1900:2254:2068::e6a:0])
 by mx1.freebsd.org (Postfix) with ESMTP id 938E91BA7;
 Sun, 23 Jun 2013 20:14:59 +0000 (UTC)
Received: from svn.freebsd.org ([127.0.1.70])
 by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5NKEx9K064331;
 Sun, 23 Jun 2013 20:14:59 GMT (envelope-from wblock@svn.freebsd.org)
Received: (from wblock@localhost)
 by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5NKEx0T064330;
 Sun, 23 Jun 2013 20:14:59 GMT (envelope-from wblock@svn.freebsd.org)
Message-Id: <201306232014.r5NKEx0T064330@svn.freebsd.org>
From: Warren Block <wblock@FreeBSD.org>
Date: Sun, 23 Jun 2013 20:14:59 +0000 (UTC)
To: doc-committers@freebsd.org, svn-doc-all@freebsd.org,
 svn-doc-head@freebsd.org
Subject: svn commit: r42006 -
 head/en_US.ISO8859-1/books/fdp-primer/writing-style
X-SVN-Group: doc-head
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: svn-doc-all@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: "SVN commit messages for the entire doc trees \(except for &quot;
 user&quot; , &quot; projects&quot; , and &quot; translations&quot;
 \)" <svn-doc-all.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/svn-doc-all>,
 <mailto:svn-doc-all-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/svn-doc-all>
List-Post: <mailto:svn-doc-all@freebsd.org>
List-Help: <mailto:svn-doc-all-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/svn-doc-all>,
 <mailto:svn-doc-all-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sun, 23 Jun 2013 20:14:59 -0000

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">