Date: Sun, 23 Jun 2013 20:14:59 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201306232014.r5NKEx0T064330@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306232014.r5NKEx0T064330>