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 the expected results. Active voice also gives the reader an impression the author stands behind the written work.
Passive voice gives the impression an author is unsure of the advice or the outcome. If clicking on a menu "should open the window," the reader wonders if the window is going to open or not. When using passive voice, make sure that it gives strength to the writing and the points being made. Often a simple restructuring of the sentence makes it active. Be careful of words such as "can," "will," and "should."
ACTIVE: Use this thing. PASSIVE: This thing should be used.
Context
Avoid writing out of context. Adhere carefully to the subject matter of the document, chapter, section, and paragraph. Use references where necessary, and structure the document so that each new part builds upon the last. Avoid making the reader skip ahead to put current parts in context.
Emphasis
Emphasis is both a valuable and dangerous tool. Use methods of emphasis such as boldface, underlining, or oblique text sparingly to avoid degrading their overall value. Use admonitions to call attention to notable material, and use subtle methods such as sentence formation or word choice for emphasis wherever possible. Plan ahead for emphasis, and apply it consistently and carefully throughout the document.
Accuracy and Precision
Accuracy and precision can make or break any document. This axiom applies equally to technical and literary accuracy. Choose words carefully and consider as many usage cases as possible. In procedures for interface interactions, for example, "go to" is not as precise as "click," and "click" may not be accurate in all usage cases. The term "select" is accurate in any usage case and is sufficiently precise. By the same token, it is not necessary to cover all potential usage cases. Covering rare side cases elongates a document beyond reason, and causes the reader to lose focus.
Tense
Select an appropriate tense for the document and adhere to it. For technical documentation, present tense is usually best. Maintain consistent and accurate tense for each statement. Present subsequent tasks in a procedure in the same tense.
Usage
Contractions
Avoid contractions. They reduce the readability of a document and make it more difficult to translate. They can also be confusing to readers from other cultures, as each culture and language may use contractions differently.
Pronouns
Avoid most personal pronouns in documentation, including the following:
- Subjective personal pronouns ("I," "he," "she," "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"
- Do not use "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.
Finally, avoid indefinite pronouns such as "this" or "that" without an antecedent, especially to start a sentence:
INCORRECT: Edit your yum configuration files to use geographically close mirrors. This allows you to update your system faster. CORRECT: For faster system updates, edit the yum configuration files to use geographically close mirrors.
An overlong sentence may result from joining clauses in this fashion. In such a situation, use of "this" or "that" is acceptable only if you provide a proper antecedent, such as "this procedure."
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.