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:

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