commit 88125f09a56fe9232e9e8a629e52c7013caadc75
Author: Robert Krátký <rkratky(a)redhat.com>
Date: Fri Aug 8 16:45:19 2014 +0200
Fix lang. and typos.
en-US/style.xml | 32 ++++++++++++++++----------------
1 files changed, 16 insertions(+), 16 deletions(-)
---
diff --git a/en-US/style.xml b/en-US/style.xml
index bff0b4a..cda5820 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -5,10 +5,10 @@
]>
<appendix id="chap-documentation_guide-style">
<title>Style Guide</title>
- <para>Writing high-quality documents that are easily understood by multiple
readers can be a difficult challenge. There are many different techniques that can be
used in writing, and there are many different ways of writing the same information. In
order to provide consistent, readable documentation, certain standards must be
established. There are many different writing style guides that serve different purposes
and audiences. Good style is something learned and practiced.</para>
- <para>The Fedora Documentation Project is tasked with producing friendly,
easy-to-read documentation for a worldwide audience. This means writing clean, clear
documents with great attention to differences in cultures and languages. The Fedora
Documentation Style Guide outlines specific rules and recommendations for documentation
contributors. The style guidelines standardize documentation of both technical and
non-technical information, to increase readability and comprehension.</para>
- <para>The writers producing Fedora documentation come from a variety of
backgrounds, each with different skill sets. Through use of the Fedora Documentation
Style Guide, contributors produce and collaborate on documentation with consistent
results. This style guide may vary from each contributor's familiar writing
requirements. Practicing this guide will eventually become a comfortable standard with
benefits outside of Fedora documentation. This style guide will demonstrate the rules and
guidelines it sets forth.</para>
- <para>The Fedora Documentation Style Guide borrows many ideas from the Associated
Press (AP) Stylebook and The Chicago Manual of Style. Any differences from those guides
are intended to enhance the value of documents for international readers, and accommodate
the technical nature of Fedora documentation. Particular care is made to adopt
international standards for common notations to avoid confusion across cultural
lines.</para>
+ <para>Writing high-quality documents that are easily understood by multiple
readers can be a difficult challenge. There are many different techniques that can be
used in writing, and there are many different ways of writing the same information. In
order to provide consistent, readable documentation, certain standards must be
established. There are many different writing-style guides that serve different purposes
and audiences. Good style is something learned and practiced.</para>
+ <para>The Fedora Documentation Project is tasked with producing friendly,
easy-to-read documentation for a worldwide audience. This means writing clean, clear
documents with great attention to differences in cultures and languages. The Fedora
Documentation Style Guide outlines specific rules and recommendations for documentation
contributors. The style guidelines standardize documentation of both technical and
non-technical information to increase readability and comprehension.</para>
+ <para>The writers producing Fedora documentation come from a variety of
backgrounds, each with different skill sets. Through the use of the <citetitle
pubwork="book">Fedora Documentation Style Guide</citetitle>,
contributors produce and collaborate on documentation with consistent results. This style
guide may vary from each contributor's familiar writing requirements. Practicing this
guide will eventually become a comfortable standard with benefits outside of Fedora
documentation. This style guide will demonstrate the rules and guidelines it sets
forth.</para>
+ <para>The <citetitle pubwork="book">Fedora Documentation Style
Guide</citetitle> borrows many ideas from the Associated Press (AP) Stylebook and
The Chicago Manual of Style. Any differences from those guides are intended to enhance the
value of documents for international readers, and accommodate the technical nature of
Fedora documentation. Particular care is made to adopt international standards for common
notations to avoid confusion across cultural lines.</para>
<section id="sect-documentation_guide-style-general_guidelines">
<title>General Guidelines</title>
@@ -22,7 +22,7 @@
<title>Voice</title>
<para>Instructions and rules use an <emphasis>active
voice</emphasis>, presenting confidence to the reader without sounding demanding.
An active voice provides clear direction. It shows the reader what to do and gives
expected results. Active voice leaves the reader with the impression an author stands
behind the written work.</para>
- <warning><title>Avoid Passive Voice Unless
Necessary</title><para>Passive voice is completely correct grammatically, but
it is a barrier to reader comprehension. The passive voice flips conventional sentence
structure around. It moves the verb and direct object forward to the first half of a
sentence, and places the main subject in the second half of a sentence. Often a simple
restructuring of the sentence makes it active. Long passive sentences frequently take
multiple reads before a reader grasps the full meaning.</para></warning>
+ <warning><para>Passive voice is completely correct grammatically, but it
is a barrier to reader comprehension. The passive voice flips conventional sentence
structure around. It moves the verb and direct object forward to the first half of a
sentence and places the main subject in the second half of a sentence. Often a simple
restructuring of the sentence makes it active. Long passive sentences frequently take
multiple reads before a reader grasps the full meaning.</para></warning>
<para>
<simplelist>
@@ -37,7 +37,7 @@
</section>
<section
id="sect-documentation_guide-style-general_guidelines-composition-emphasis">
<title>Emphasis</title>
- <para>Emphasis is most effective when used sparingly. Use methods of emphasis
such as boldface, underlining, or oblique text to draw attention to a new term. Use
admonitions to set off notable material. Another acceptable way to emphasize a point is
with varying sentence formation or word choice. The best documentation writers plan ahead
for emphasis, applying it with careful consistency throughout the document.</para>
+ <para>Emphasis is most effective when used sparingly. Use methods of emphasis,
such as boldface, underlining, or oblique text, to draw attention to a new term. Use
admonitions to set off notable material. Another acceptable way to emphasize a point is
with varying sentence formation or word choice. The best documentation writers plan ahead
for emphasis, applying it with careful consistency throughout the document.</para>
</section>
<section
id="sect-documentation_guide-style-general_guidelines-composition-accuracy_and_precision">
<title>Accuracy and Precision</title>
@@ -57,7 +57,7 @@
</section>
<section
id="sect-documentation_guide-style-general_guidelines-Usage-Pronouns">
<title>Pronouns</title>
- <para>Pronouns are words language uses to replace specific noun phrases. Good
writers must strike a balance between over-repeating a noun phrase, and using pronouns to
stand in for nouns. A general rule to preserve clarity is to never repeat noun
substitution with a pronoun in two consecutive sentences. Readers of technical documents
need constant reminders on the exact subject the author is writing about. Prevalent use of
pronouns cause readers to guess the subject a sentence is referencing. These assumptions
reduce the effectiveness of documentation.</para>
+ <para>Pronouns are words languages use to replace specific noun phrases. Good
writers must strike a balance between over-repeating a noun phrase and using pronouns to
stand in for nouns. A general rule to preserve clarity is to never repeat noun
substitution with a pronoun in two consecutive sentences. Readers of technical documents
need constant reminders on the exact subject the author is writing about. Prevalent use of
pronouns causes readers to guess the subject a sentence is referencing. These assumptions
reduce the effectiveness of documentation.</para>
<para>Avoid most personal pronouns in documentation, including the following:
<simplelist>
<member>Subjective personal pronouns ("I," "he,"
"she," "it," "we,")</member>
@@ -72,8 +72,8 @@
<member>Resist overuse of "you", "your", and
"one/one's"</member>
</simplelist>
</para>
- <para>Occasionally situations require the second personal pronoun
"you," and its attendant forms for clarity. Maintaining an active voice is
paramount over avoiding the second personal pronouns. "You" and
"your" are appropriate words to indicate action or possession on the part of the
reader.</para>
- <para>Indefinite pronouns such as "this" or "that" without
an antecedent make it tough for a reader to follow an author's meaning. Favor writing
an exact noun phrase whenever possible over the vague words "this,"
"these," "those," and "that."</para>
+ <para>Occasionally, situations require the second personal pronoun
"you" and its attendant forms for clarity. Maintaining an active voice is
paramount over avoiding the second personal pronouns. "You" and
"your" are appropriate words to indicate action or possession on the part of the
reader.</para>
+ <para>Indefinite pronouns, such as "this" or "that",
without an antecedent make it tough for a reader to follow an author's meaning. Favor
writing an exact noun phrase whenever possible over the vague words "this",
"these", "those", and "that."</para>
<para>
<simplelist>
<member>INCORRECT: Edit your yum configuration files to use geographically
close mirrors. This allows you to update your system faster.</member>
@@ -93,7 +93,7 @@
<para>Keep sentences as short as possible. Cutting unnecessary words is vital
to strengthen meaning. There are a number of common traps technical writers fall into
resulting in lengthy sentences.</para>
<section>
<title>Indirect Discourse</title>
- <para>Indirect discourse refers to the use of "that" to attribute a
statement, fact, or feeling in a sentence without the use of quotation marks. In regular
writing, it weakens statements of fact. Documentation writers can improve the impact of
sentences by removing "that" and "which."</para>
+ <para>Indirect discourse refers to the use of "that" to attribute a
statement, fact, or feeling in a sentence without the use of quotation marks. In regular
writing, it weakens statements of fact. Documentation writers can improve the impact of
sentences by removing "that" and "which".</para>
<simplelist>
<member>INCORRECT: Fedora is an open source operating system that is upstream
for many other open source projects.</member>
<member>CORRECT: Fedora is an upstream open source operating system for many
other open source projects.</member>
@@ -107,12 +107,12 @@
<member>CORRECT: If an email client will not send or receive messages, check
under the File Menu and verify "Work Offline" mode is
unselected.</member>
</simplelist>
</para>
- <para>Many words we use in everyday conversation reduce impact in printed
materials because they "leave a way out." These are words preceding verbs and
nouns to minimize the sentence's influence. This is not an exhaustive list, but
mindful documentation writers will reduce using these words and those of a similar
nature.</para>
- <warning><title>Avoid Reducing Impact With Unnecessary
Words</title><para>The following words minimize the impact of the verb or noun
clause within a sentence. Other words also fit into this category, but this short list is
aimed at helping documentation writers identify words of this nature and eliminate them
from their writing: should, could, may, might, perhaps, some, many, most, numerous, few,
somewhat, whatever, possibly, can, occasionally, and
frequently.</para></warning>
+ <para>Many words we use in everyday conversation reduce impact in printed
materials because they "leave a way out". These are words preceding verbs and
nouns to minimize the sentence's influence. This is not an exhaustive list, but
mindful documentation writers will reduce using these words and those of a similar
nature.</para>
+ <warning><para>The following words minimize the impact of the verb or
noun clause within a sentence. Other words also fit into this category, but this short
list is aimed at helping documentation writers identify words of this nature and eliminate
them from their writing: should, could, may, might, perhaps, some, many, most, numerous,
few, somewhat, whatever, possibly, can, occasionally, and
frequently.</para></warning>
</section>
<section>
<title>Sentence Variation</title>
- <para>For the strongest impact, keep the first and last sentences of a
paragraph as short as possible. Varying sentence length within a paragraph and through the
entire document keeps a reader's attention. A short and simple fact is easy to grasp
and use to analyze the next sentence's topic. There is nothing wrong with using longer
sentences to explain complex ideas and concepts. Try to use a simple synopsis sentence at
the end of each paragraph to give readers a reprieve and recap of any important
information. A short final sentence stays with the reader to the next
section.</para>
+ <para>For the strongest impact, keep the first and last sentences of a
paragraph as short as possible. Varying sentence length within a paragraph and through the
entire document keeps a reader's attention. A short and simple fact is easy to grasp
and use to analyze the next sentence's topic. There is nothing wrong with using longer
sentences to explain complex ideas and concepts. Try to use a simple synopsis sentence at
the end of each paragraph to give readers a reprieve and recap any important information.
A short final sentence stays with the reader to the next section.</para>
</section>
</section>
<section
id="sect-documentation_guide-style-general_guidelines-Usage-capitalization">
@@ -123,7 +123,7 @@
<member>CORRECT: The <code>smolt</code> package provides hardware
profiling.</member>
</simplelist>
</para>
- <para>In headings, always capitalize the first word regardless of the type of
speech. All subsequent words are also capitalized other than articles ("a,"
"an," or "the"), short prepositions ("in," "of,"
"for," "with," "at," "on"), or conjunctions
("and," "but," "or").</para>
+ <para>In headings, always capitalize the first word regardless of the type of
speech. All subsequent words are also capitalized other than articles ("a",
"an", or "the"), short prepositions ("in", "of",
"for", "with", "at", "on"), or conjunctions
("and", "but", "or").</para>
<para>Examples:
<simplelist>
<member>Avoid Using Contractions in Technical Writing</member>
@@ -139,8 +139,8 @@
<para>Minimize the following punctuation marks in documentation:
<simplelist>
<member><emphasis>Parentheses or em dashes</emphasis> - To
compensate, rearrange the sentence, or break it into two complete
thoughts.</member>
- <member><emphasis>Semicolons</emphasis> - Good to use only if two
thoughts are related, must be joined for clarity, and removes the need for a
conjunction.</member>
- <member><emphasis>Colon</emphasis> - If there are more than three
items, use a bulleted list for easy comprehension.</member>
+ <member><emphasis>Semicolons</emphasis> - Good to use only if two
thoughts are related, must be joined for clarity, and remove the need for a
conjunction.</member>
+ <member><emphasis>Colon</emphasis> - If there are more than three
items, use a bullet list for easy comprehension.</member>
<member><emphasis>Ellipsis</emphasis> - Do not use for stylistic
emphasis... only to denote an indefinite continuation of content in an
example.</member>
<member><emphasis>Exclamation points</emphasis> - In technical
writing this is accepted for use only as a most dire "warning" admonition, not
for emphasis.</member>
<member><emphasis>Ampersands</emphasis> - The word "and"
is to be written out, and this mark only reserved if it is part of a computer
command.</member>