os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add some suggestions on writing style to the FDP.

Browse source 
Reviewed by:	dru,trhodes
This commit is contained in:
Warren Block 2013-06-17 20:16:00 +00:00
parent c2d3386d81
commit 9592140393
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=41937
1 changed files with 56 additions and 1 deletions

57
en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
View file

@ -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>