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

Warren Block wblock at FreeBSD.org
Thu Jun 20 16:40:43 UTC 2013 

Author: wblock
Date: Thu Jun 20 16:40:42 2013
New Revision: 41970
URL: http://svnweb.freebsd.org/changeset/doc/41970

Log:
  Rearrange the Writing Style chapter.  Move new tips to a new section,
  and organize them into clear, complete, and concise categories.

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	Thu Jun 20 16:39:11 2013	(r41969)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Thu Jun 20 16:40:42 2013	(r41970)
@@ -34,7 +34,81 @@
 <chapter id="writing-style">
   <title>Writing Style</title>
 
-  <para>In order to promote consistency between the myriad authors of
+  <sect1 id="writing-style-tips">
+    <title>Tips</title>
+
+    <para>Technical documentation can be improved by consistent use of
+      several principes.  Most of these can be classified into three
+      goals: <emphasis>be clear</emphasis>,
+      <emphasis>be complete</emphasis>, and
+      <emphasis>be concise</emphasis>.  These goals can conflict with
+      each other.  Good writing consists of a balance between
+      them.</para>
+
+    <sect2 id="writing-style-be-clear">
+      <title>Be Clear</title>
+
+      <para>Clarity is extremely important.  The reader may be a
+	novice, or reading the document in a second language.  Strive
+	for simple, uncomplicated text that clearly explains the
+	concepts.</para>
+
+      <para>Avoid flowery or embellished speech, jokes, or colloquial
+	expressions. Write as simply and clearly as possible.  Simple
+	text is easier to understand and translate.</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>
+
+      <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>
+
+      <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>
+
+      <para>Similarly, give instructions as imperative commands: not
+	<quote>you should do this</quote>, but merely
+	<quote>do this</quote>.</para>
+    </sect2>
+
+    <sect2 id="writing-style-be-complete">
+      <title>Be Complete</title>
+
+      <para>Do not make assumptions about the reader's abilities or
+	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>
+    </sect2>
+
+    <sect2 id="writing-style-be-concise">
+      <title>Be Concise</title>
+
+      <para>While features should be documented completely, sometimes
+	there is so much information that the reader cannot easily
+	find the specific detail needed.  The balance between being
+	complete and being concise is a challenge.  One approach is to
+	have an introduction, then a <quote>quick start</quote>
+	section that describes the most common situation, followed by
+	an in-depth reference section.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="writing-style-guidelines">
+    <title>Guidelines</title>
+
+  <para>To promote consistency between the myriad authors of
     the FreeBSD documentation, some guidelines have been drawn up for
     authors to follow.</para>
 
@@ -170,6 +244,7 @@
   <para>For more information about writing style, see <ulink
       url="http://www.bartleby.com/141/">Elements of
       Style</ulink>, by William Strunk.</para>
+  </sect1>
 
   <sect1 id="writing-style-guide">
     <title>Style Guide</title>
@@ -212,61 +287,6 @@
 	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>
 
@@ -459,7 +479,7 @@ GB.  Hardware compression …</lite
 
     <para>This list of words shows the correct spelling and
       capitalization when used in FreeBSD Documentation.  If a word is
-      not on this list, ask about that word on the &a.doc;.</para>
+      not on this list, ask about it on the &a.doc;.</para>
 
     <informaltable frame="none" pgwide="0">
       <tgroup cols="2">
@@ -473,12 +493,12 @@ GB.  Hardware compression …</lite
 	<tbody>
 	  <row>
 	    <entry>CD-ROM</entry>
-	    <entry><![CDATA[<acronym>CD-ROM</acronym>]]></entry>
+	    <entry><literal><![CDATA[<acronym>CD-ROM</acronym>]]></literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>DoS (Denial of Service)</entry>
-	    <entry><![CDATA[<acronym>DoS</acronym>]]></entry>
+	    <entry><literal><![CDATA[<acronym>DoS</acronym>]]></literal></entry>
 	  </row>
 
 	  <row>
@@ -523,7 +543,7 @@ GB.  Hardware compression …</lite
 
 	  <row>
 	    <entry>&unix;</entry>
-	    <entry><![CDATA[&unix;]]></entry>
+	    <entry><literal><![CDATA[&unix;]]></literal></entry>
 	  </row>
 
 	  <row>

More information about the svn-doc-head mailing list