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

[Warren Block]

Author: wblock
Date: Mon Jun 17 20:16:00 2013
New Revision: 41937
URL: http://svnweb.freebsd.org/changeset/doc/41937

Log:
  Add some suggestions on writing style to the FDP.
  
  Reviewed by:	dru,trhodes

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	Mon Jun 17 19:54:32 2013	(r41936)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Mon Jun 17 20:16:00 2013	(r41937)
@@ -205,13 +205,68 @@
 	also define them the first time they appear in each
 	chapter.</para>
 
-      <para>The first three uses of an acronym should be enclosed in
+      <para>All acronyms should be enclosed in
 	<sgmltag>acronym</sgmltag> tags, with a
 	<literal>role</literal> attribute with the full term defined.
 	This allows a link to the glossary to be created, and for
 	mouseovers to be rendered with the fully expanded term.</para>
     </sect2>
 
+    <sect2 id="writing-style-beformal">
+      <title>Be Formal</title>
+
+      <para>Write in a formal style.  Avoid addressing the reader
+	as <quote>you</quote>.  For example, say
+	<quote>copy the file to <filename>/tmp</filename></quote>
+	rather than <quote>you can copy the file to
+	  <filename>/tmp</filename></quote>.</para>
+    </sect2>
+
+    <sect2 id="writing-style-confident">
+      <title>Be Confident</title>
+
+      <para>Avoid <emphasis>weasel words</emphasis> like
+	<quote>should</quote>, <quote>might</quote>,
+	<quote>try</quote>, or <quote>could</quote>.  These words
+	imply that the speaker is unsure of the facts, and
+	create doubt in the reader.</para>
+    </sect2>
+
+    <sect2 id="writing-style-imperative">
+      <title>Be Imperative</title>
+
+      <para>Give instructions as an imperative command: not
+	<quote>you should do this</quote>, but merely
+	<quote>do this</quote>.</para>
+    </sect2>
+
+    <sect2 id="writing-style-simple">
+      <title>Be Simple</title>
+
+      <para>Avoid flowery or embellished speech, jokes, or colloquial
+	expressions.  Write as simply and clearly as possible.  Simple
+	text is easier to understand and makes the job of translation
+	easier.</para>
+
+      <para>Keep explanations as short, simple, and clear as possible.
+	Avoid empty phrases like <quote>in order to</quote>, which
+	usually just means <quote>to</quote>.  Avoid potentially
+	patronizing words like <quote>basically</quote>.  Avoid Latin
+	terms like <quote>i.e.</quote> or <quote>cf.</quote>, which
+	may be unknown outside of academic or scientific
+	groups.</para>
+    </sect2>
+
+    <sect2 id="writing-style-threecs">
+      <title>Use the <quote>Three C</quote> Approach</title>
+
+      <para>Writing must be <emphasis>clear</emphasis>,
+	<emphasis>complete</emphasis>, and
+	<emphasis>concise</emphasis>.  These goals can conflict with
+	each other.  Good writing consists of a balance between
+	them.</para>
+    </sect2>
+
     <sect2>
       <title>Indentation</title>