Chapter 8. Style

8.1. Why Style Is Important
8.2. Fundamental Concepts of Technical Documentation
8.2.1. General Style Requirements
8.2.2. Golden Rules
8.2.3. Tone
8.2.4. Reaching the Right Audience
8.2.5. User Motivation
8.2.6. New Users
8.2.7. Experienced Users
8.2.8. Do Not Offend Your Audience
8.3. Grammar and Usage Guidelines
8.4. Composition Tips
8.4.1. Active Voice
8.4.2. Present Tense
8.4.3. Narrative Voice
8.4.4. Negative Words
8.4.5. Uncertainty
8.4.6. Redundant Coverage
8.4.7. Self-referential Value Judgments
8.4.8. Precision of Language
8.4.9. DocBook Tips
8.4.9.1. Admonitions
8.4.9.2. The <replaceable> Tag
8.4.9.3. XML Entities

Writing good technical documentation is not simply reproducing command lines and instruction sets. Good documentation is easy to read, understand, and translate, and presents a concise logical progression of concepts. Good documentation can also be defined by what it does not contain. Your tutorial should avoid:

This chapter contains style rules and guidelines for writing Fedora documentation. Guidelines are not the same as rules. It is acceptable to violate a guideline when it makes your material easier to understand. Follow guidelines whenever possible, but follow rules at all times. Assume any advice is a guideline unless identified otherwise.

8.1. Why Style Is Important

Writing well comes naturally to almost no one. It is a skill that professional writers, even famous ones, must practice constantly. Style is the quality that separates elegant writing from the merely functional.

Elegance comes in many forms. In prose and poetry, elegant writing may not follow some (or any) common rules of grammar, syntax, or spelling. A good example is Episode 18, "Penelope," in James Joyce's novel Ulysses[3]. There, Joyce uses long streams of words without punctuation to simulate a character's internal consciousness. By violating basic rules of grammar and syntax, Joyce simulates the disorganized but loosely connected thought patterns of the narrator.

Technical documentation, however, should always respect these rules. The more a document departs from standard language usage, the more difficult the material becomes for the reader. For example, readers may not be native speakers of the language used, or they might be reading a translation. If the writer uses slang, idioms, or jargon, a reader or translator may easily become confused. The following example compares two different written executions of the same idea:

So you made the changes I showed you in the last section. What's the next thing you should do? Just pop your thumb drive onto your system and read the messages log. When you see "USB device found," then Bob's your uncle.

Example 8.1. Incorrect style

After you complete the configuration changes above, attach the USB removable media to your system. Use the dmesg command to examine the kernel message log. The message USB device found indicates that your device was installed successfully.

Example 8.2. Correct style

The first example is more conversational English, which is not appropriate for official written documentation. The second example is more formal, but as a result it is easier to comprehend, both for native readers and translators.

Following style rules and guidelines also makes readers more comfortable with a set of documents. Consistent style enhances the professional appearance of documentation, and its perceived value. On the other hand, lapses in punctuation or poor grammar negatively affect a reader's reaction to written material. A reader can feel that an otherwise correct technical document is lacking in authority, simply because it is poorly written. Readers feel at ease when they do not have to struggle to understand an author's use of language.

This chapter cannot possibly cover enough material to make every reader a good writer. Some manuals devoted entirely to writing style are themselves hundreds of pages long. This chapter provides enough guidelines for intermediate writers to understand style usage in technical documentation.

If you are not a practiced writer, whether of technical documentation or otherwise, you may benefit from other style resources. The following list is far from comprehensive, but provides a starting point:

There are many free software documentation projects which have developed their own style guidelines. This chapter, in fact, draws heavily on the GNOME Documentation Style Guidelines (GDSG). You may read the original GDSG at http://developer.gnome.org/documents/style-guide/.



[3] For example, refer to. http://www.online-literature.com/james_joyce/ulysses/18/. Please note that this example contains some mature themes and language, and is not suitable for all readers.