diff options
author | Warren Block <wblock@FreeBSD.org> | 2013-06-17 20:16:00 +0000 |
---|---|---|
committer | Warren Block <wblock@FreeBSD.org> | 2013-06-17 20:16:00 +0000 |
commit | 9592140393cd2e096d588b39ea5e58ae1849a2df (patch) | |
tree | 4e1ebd81090a833644b882b16464450bf24c28bc | |
parent | c2d3386d81a82ff2c18ed8d0ef6c7506b9ccd2ce (diff) | |
download | doc-9592140393cd2e096d588b39ea5e58ae1849a2df.tar.gz doc-9592140393cd2e096d588b39ea5e58ae1849a2df.zip |
Add some suggestions on writing style to the FDP.
Reviewed by: dru,trhodes
Notes
Notes:
svn path=/head/; revision=41937
-rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml | 57 |
1 files changed, 56 insertions, 1 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml index 44f4b217f9..02cc62393c 100644 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml @@ -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> |