os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a tip about examples.

Browse source
This commit is contained in:
Warren Block 2013-06-23 20:14:59 +00:00
parent 4047241ce6
commit 3a6e0abebd
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=42006
1 changed files with 11 additions and 1 deletions

12
en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
View file

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