Archive:Docs Project Style Guide - General Guidelines

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (Contractions)
(Defined pronouns and explained why their use hinders a reader's comprehension. Gave a full example of what is meant by antecedent)
Line 42: Line 42:
  
 
==== Pronouns ====
 
==== Pronouns ====
 +
 +
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.
  
 
Avoid most personal pronouns in documentation, including the following:
 
Avoid most personal pronouns in documentation, including the following:
  
* Subjective personal pronouns ("I," "he," "she," "we")
+
* Subjective personal pronouns ("I," "he," "she," "it," "we,")
 
* Objective personal pronouns ("me," "her," "him," "us")
 
* Objective personal pronouns ("me," "her," "him," "us")
 
* Possessive personal pronouns ("my," "her," "his," "our")
 
* Possessive personal pronouns ("my," "her," "his," "our")
Line 53: Line 55:
 
* Reflexive pronouns, such as "yourself" or "himself"
 
* Reflexive pronouns, such as "yourself" or "himself"
 
* Intensive pronouns, such as "he himself" or "(you) do it yourself"
 
* Intensive pronouns, such as "he himself" or "(you) do it yourself"
* Do not use "you", "your", and "one/one's"
+
* Resist overuse of "you", "your", and "one/one's"
  
Some situations require the use of the second person pronoun "you," and its attendant forms, for clarity.  Maintaining the active voice is a higher priority than avoiding these pronouns.  "You" and "your" are sometimes necessary to indicate action or possession on the part of the reader.
+
Occasionally situations require the second person pronoun "you," and its attendant forms for clarity.  Maintaining an active voice is paramount over avoiding the second person pronouns.  "You" and "your" are appropriate words to indicate action or possession on the part of the reader.  
  
Finally, avoid indefinite pronouns such as "this" or "that" without an antecedent, especially to start a sentence:
+
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."
  
 
<pre>
 
<pre>
Line 63: Line 65:
 
geographically close mirrors.  This allows you to
 
geographically close mirrors.  This allows you to
 
update your system faster.
 
update your system faster.
CORRECT:  For faster system updates, edit the yum
+
CORRECT:  Edit the yum configuration files to use geographically close mirrors for faster system updates.
configuration files to use geographically close mirrors.
+
 
</pre>
 
</pre>
  
An overlong sentence may result from joining clauses in this fashionIn such a situation, use of "this" or "that" is acceptable ''only'' if you provide a proper antecedent, such as "this procedure."
+
When eliminating indefinite pronouns, a cumbersome long sentence may result from joining too many clauses.  Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent.  
 +
 
 +
<pre>
 +
INCORRECT: Edit your yum configuration files to use geographically close mirrors.
 +
This allows you to update your system faster.
 +
CORRECT: Edit your yum configuration files to use geographically close mirrors.
 +
This configuration change allows you to update your system faster.
 +
</pre>
  
 
==== Sentence Formation ====
 
==== Sentence Formation ====

Revision as of 17:46, 21 September 2008

DocsProject Header docTeam1.png


Contents

General Guidelines

The following sections provide guidelines for both sentence composition and syntax usage. Follow these guidelines to ensure your document's tone is consistent with that of other Fedora documentation.

Composition

Voice

Instructions and rules use an active voice, 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.

Important.png
Avoid passive voice unless necessary
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 full meaning.


ACTIVE:  Select a strong password to improve personal security.
PASSIVE: Personal security improves by a strong password being selected.

Context

Avoid writing out of context. Adhere carefully to the subject matter of the document, chapter, section, and paragraph. Use references as appropriate, structuring documents so each new part builds upon the last. Avoid making the reader skip ahead to put current parts in context. Provide a link to related documentation if the reader may need it for clarification.

Emphasis

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.

Accuracy and Precision

Accuracy and precision make or break any document. This axiom applies equally to technical and literary accuracy. Choose words after considering as many usage cases as possible. For example, "go to" is not as precise as "click," yet "click" may not be accurate for all interface interactions. The term "select" is accurate in any usage case and sufficiently precise. Don't become too preoccupied in an attempt to cover all potential usage cases. Covering rare side cases elongates a document beyond reason, and the reader loses focus.

Tense

Tense is the time in which language takes place. There are three main tenses: past, present, and future. Select an appropriate tense for the document and adhere to it. For technical documentation, use the present tense whenever possible. Maintaining the same tense for each statement in a document is vital for clarity. Keep the same tense for all sequential tasks in a procedure.

Usage

Contractions

Avoid contractions, the combination of two words with an apostrophe replacing one or more letters. Contractions reduce the readability of documents and make translation more difficult. Other cultures and languages interpret contractions differently, and this confusion conflicts with the goals of the Fedora Documentation Project.

Pronouns

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.

Avoid most personal pronouns in documentation, including the following:

  • Subjective personal pronouns ("I," "he," "she," "it," "we,")
  • Objective personal pronouns ("me," "her," "him," "us")
  • Possessive personal pronouns ("my," "her," "his," "our")

Also avoid:

  • Reflexive pronouns, such as "yourself" or "himself"
  • Intensive pronouns, such as "he himself" or "(you) do it yourself"
  • Resist overuse of "you", "your", and "one/one's"

Occasionally situations require the second person pronoun "you," and its attendant forms for clarity. Maintaining an active voice is paramount over avoiding the second person pronouns. "You" and "your" are appropriate words to indicate action or possession on the part of the reader.

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."

INCORRECT:  Edit your yum configuration files to use
geographically close mirrors.  This allows you to
update your system faster.
CORRECT:  Edit the yum configuration files to use geographically close mirrors for faster system updates.

When eliminating indefinite pronouns, a cumbersome long sentence may result from joining too many clauses. Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent.

INCORRECT: Edit your yum configuration files to use geographically close mirrors. 
This allows you to update your system faster.
CORRECT: Edit your yum configuration files to use geographically close mirrors. 
This configuration change allows you to update your system faster.

Sentence Formation

Avoid using the unnecessary word "then" following an "if" statement. If a sentence begins with an "if" statement, follow it with a comma and complete the sentence with a full statement.

Capitalization

In sentences, capitalize the first word. Do not start sentences with a command, package, or option name, to avoid breaking this rule.

INCORRECT: <code>smolt</code> provides hardware profiling.
CORRECT: The <code>smolt</code> package provides hardware profiling.

In headings, capitalize the first word and any other word that is not an article ("a," "an," or "the"), a short preposition ("in," "of," "for," "with," "at," "on"), or a conjunction ("and," "but," "or"). Examples:

  • Avoid Using Contractions in Technical Writing
  • Try to Do the Right Thing
  • Find the Right Way to Say What You Mean

Punctuation

Avoid the following punctuation in sentences:

  • Parentheses or "em dashes," which usually indicate the writer should restructure a sentence, possibly into two or more sentences
  • Semicolons, which usually indicate the writer should break a sentence in two, or use bullets or a numbered procedure in place of a sequential list
  • Ellipsis, except where used to denote an indefinite continuation of the same or similar content in an example
  • Exclamation points, except in the most dire "warning" admonitions
  • Ampersands, for which the writer should use the word "and"
  • Slashes, as in "he/she," "s/he," and "and/or," for which the writer should find an alternate sentence construction, or use the word "or"

The Unknown

Every writer encounters issues that are difficult to solve. When such an issue arises, do research to find an adequate solution for present and future instances of the issue, or write around the issue instead. For example, if it is unclear whether to use a comma in a sentence, rewrite the sentence differently, or split it into two sentences to avoid the issue entirely.