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