*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.
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.
Do not 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.
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 OpenMandriva Documentation Project.
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.
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.
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: If an email client will not send or receive messages, then check under the File Menu and verify "Work Offline" mode is unselected.`
`CORRECT: If an email client will not send or receive messages, check under the File Menu and verify "Work Offline" mode is unselected.`
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.
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**.
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.
Punctuation is a crucial component of understanding prose.
A misplaced comma, period, or an improper punctuation mark changes a sentence meaning entirely. Punctuation marks are the fasteners in a writer's toolbox. Readers are accustomed to the regular nails and screws, like commas and periods. Start throwing in lots of flashy hinges or braces like semicolons or ellipsis, and the unfamiliar notations easily distract readers.
Complex punctuation marks are not universal, hindering translation efforts of OpenMandriva Documentation.
Do not use slashes for a short hand version of "he or she" by using he/she, instead use the words "and," "or," or "either." Slashes are commonly used in file paths and using them otherwise will create confusion
Every writer hits writing obstacles. It becomes difficult to adequately phrase something, or the words just do not "sound right."
This is why the Openmandriva Project is a team effort. Call on fellow documentation writers in the mailing list or chat room for help with wording and formatting issues.
Another trick professional writers use everyday is time away from the project. Take a break away from the document. Returning to a troublesome spot with fresh eyes is often all that is needed to overcome the writing hindrance.
The overall goal of the OpenMandriva Documentation Project is to provide assistance to OpenMandriva users in easy-to-understand language.
You do not have to write to impress an English professor, or show off your expertise in a subject matter. Short sentences, frequent definitions of new and unfamiliar terms, and reference links are all aids our audience appreciates most.
Write with your target audience in mind, and it will be your documentation contributions with the highest visits of users in need of answers.
