[documentation-guide] Fix lang. and typos.
rkratky
rkratky at fedoraproject.org
Fri Aug 8 14:45:53 UTC 2014
commit 88125f09a56fe9232e9e8a629e52c7013caadc75
Author: Robert Krátký <rkratky at 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>
More information about the docs-commits
mailing list