[documentation-guide] added content to sect-documentation_guide-style-be_professional
Pete Travis
immanetize at fedoraproject.org
Tue Oct 25 15:51:07 UTC 2011
commit be28b61c228318d70b0f1d648669a92dd17bacfe
Author: Pete Travis <me at petetravis.com>
Date: Mon Oct 24 23:47:40 2011 -0600
added content to sect-documentation_guide-style-be_professional
en-US/style.xml | 10 +++++++---
1 files changed, 7 insertions(+), 3 deletions(-)
---
diff --git a/en-US/style.xml b/en-US/style.xml
index 8fb1908..c6fd39f 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -6,12 +6,13 @@
<chapter id="chap-documentation_guide-style">
<title>Style Guide</title>
<para>
- Your writing should be styled consistently and concisely. This section will outline style conventions to be used when writing documentation.
+ Your writing should be styled consistently and concisely. This section will outline
+ style conventions to be used when writing documentation.
</para>
<section id="sect-documentation_guide-style-be_direct">
<title>Be Direct</title>
<para>
- Get straight to the point. Embellishments used in spoken language does not add value to a technical document.
+ Get straight to the point. Embellishments used in spoken language do not add value to a technical document.
Be sparing with qualifiers like "usually," "should," and "often."
The progression of the document will be apparent, avoid narrative language such as
"now that we have configured with the file, we are going to issue a command."
@@ -26,7 +27,10 @@
<section id="sect-documentation_guide-style-be_professional">
<title>Be Professional</title>
<para>
- Keep your writing relevant and impersonal.
+ Keep your writing relevant and impersonal. Don't refer to the writer in the first person with
+ "I," "we," or "us," or the reader in the third person singular. Using "you" is acceptable when
+ giving instructions, but should be avoided in any statement of fact. "You" is preferred to the
+ gender-specific "he" or "she," the awkward "he or she," the ugly "s/he," and the excessively dry "one."
</para>
</section>
<section id="sect-documentation_guide-style-be_accurate">
More information about the docs-commits
mailing list