Date: Thu, 20 Jun 2013 16:40:42 +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: r41970 - head/en_US.ISO8859-1/books/fdp-primer/writing-style Message-ID: <201306201640.r5KGegSU092582@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306201640.r5KGegSU092582>