DocumentationStyleGuide

Documentation Style Guide

This is still a work in progress, and no doubt commits some of the errors it tries to describe, or those described in The Elements of Style which it refers to. If you have any comments or corrections to suggest about this document, please send them to [email protected].

Clear writing is hard. Explaining a complex subject like computer software to a novice audience is difficult because you, the writer, are immersed in technical details before you even begin writing.

Your task is to bring the reader to a level of familiarity with your subject equal to, or at least close to, your own familiarity. Writing in an unclear way, or drowning the reader in technical details will confuse them, cause them to "skim" the material, and come away with bad or false impressions of you or your subject.

This guide gives you practical advice, from my own writing experience, to help you develop clear, instructive, maintainable, and ultimately valuable software documentation. What follows is a series of rules that you can apply to what you've written, or are going to write, to improve the documentation you produce.

These rules do not attempt to cover the most common English usage and composition errors. I consider the best resource of usage and composition rules to be The Elements of Style by William Strunk, Jr. A follow up of this book, edited and expanded by E. B. White, is also available (and is the most common edition found in bookstores). The Elements of Style is indispensable for anyone whose task is to write clear English. While the rules presented here are inspired by, and often reiterate, rules and concepts from The Elements of Style, their focus is primarily toward writing clear documentation for computer software, or anything equivalently technical.

Michel Pelletier

1. Speak directly to the reader.

   Address the reader in the second person as "you" , and use the possessive "your".

   Use first person sparingly and only to refer to yourself: the writer. "We" should not be used to include yourself with the reader, but only to refer to multiple authors. Here is an example of text that includes the author with the reader:

         "When we add a new method to this class, it will override any methods
         with the same name defined in our subclasses."
   

   This is often referred to as "The Royal We". Fixing this is almost always a simple transformation:

         "When you add a new method to this class, it will override any methods
         with the same name defined in your subclasses."
   

2. Be assertive.

   Do not speak in a weak, indefinite, or probable way.

   As described in The Elements of Style (rule #11), use the active voice. This is so common an error it is worth repeating here with some examples. Active voice means engaging the subject of a sentence with an active verb. The opposite, passive voice, usually involves saying that the subject constantly is doing some infinitive action. For example:

         "Something to remember about ZPublisher is that it will refuse to
         publish any method that doesn't have a doc string."
   
         "The standard convention for product management is to provide a
         series of tabbed management screens."
   

   Here are the same sentences speaking in active voice. Notice how this sometimes involves rearranging the sentence:

         "ZPublisher refuses to publish any method that lacks a doc string."
   
         ShaneH (2000-11-01) -- Nitpick: this revised sentence does not
           emphasize the point as well as the first did.  It needs to be
           phrased in such a way that the reader is tempted to write it
           down or read it twice.  What would you suggest?
   
         "Tabbed management screens provide a standard convention for product
         management."
   

   Do not speak in probable terms like may, maybe, or probably. This is often the unconscious effect of writing documentation before the software it describes is written. Be assertive, and state what is, not what may be. "Maybe" can be struck entirely. "May be" and "probably is" can be replaced by "is". "Should" sometimes falls under this rule also.

3. Explain key ideas in simple terms.

   Documentation should explain key ideas to the reader. Often, these ideas are not obvious to the reader when they use the software, and therefore must be explained.

   Writers are tempted to explain key ideas in terms of concrete technical details those ideas are based on. Readers, however, are often uninterested (at least initially) in the technical details that implement a key idea. Would you describe a building to a cave-dweller as a shelter from the elements, or a collection of bricks, boards, nails and other materials? Would you describe a car as an object that transports you from one place to another, or as a machine with pistons, brakes, wires and other parts? The first of these descriptions are the key ideas, the second of them are the details that implement the key ideas. If your audience seeks implementation details and is already familiar with the key idea then detailed explanation is correct. If you audience is the equivalent of a cave-dweller to your subject, then you must avoid implementation and focus on the key idea at first.

   When a reader fails to understand the meaning of documentation, it is usually because they encounter a word they do not understand. Clear explanation involves building a key idea in the readers mind using a succession of simple terms they can understand. When you throw an implementation detail in the explanation before they key idea is completed the reader stumbles; resulting in confusion. The reader skims over the technical parts that they don't understand yet, or can't understand yet, because you have not completed explaining the key idea to them. For example, the first paragraph of a draft of user documentation for Zope's Python Methods states:

         "All of Zope's capabilities are provided by methods, one way or
         another. When you ask Zope for a URL, it first fetches an object from
         the ZODB and then calls some method of that object. The methods of
         built-in Zope objects are defined in Zope's source code, or in Python
         classes stored in Product modules on the filesystem. Additional
         object classes (and their methods) can be defined by creating new
         filesystem Products, and this is appropriate when the implementation
         of a class requires extensive access to resources (such as the
         filesystem) which should be carefully protected."
   

   Before readers can even begin to understand what this paragraph is really saying they must understand ZODB, methods on objects, built-in Zope objects, what or where Zope's source code is, Python classes, Product modules, the file-system, object classes (and their methods), file-system Products, and why implementing them involves a class if it requires extensive access to resources which should be carefully protected. The first sentence should really say something like:

         "You can write simple scripts in Zope in the Python programming
         language with Python Methods."
   

   Students in Driver's Education do not learn how to use a steering wheel by being told about rack-and-pinions, Cardon shafts, toe, castor or double-wishbone suspensions. None of these technical details are relevant to steering a car.

   ShaneH? (2000-11-01)

   On the other hand, you should know your audience. Mechanics and car buyers do want to be told about rack-and-pinions, etc.

4. Use simple examples.

   XXX

5. Avoid colloquial expression.

   Speak simply. If your audience is global, you cannot assume your reader's native language is English. Colloquial speech is unnecessary and distracting for a reader that struggles to understand not only the concept your are describing, but also the language you are describing it in.

   XXX

   Should be written as:

   XXX

6. Provide answers, not questions.

   It is tempting to ask a question followed immediately by the answer. For example:

         "What if you want the reptile page to display something besides the
         welcome message? You can replace the *index_html* method in the
         reptile section with a more appropriate display method, and still
         take advantage of the zoo header and footer including navigation."
   

   The question serves only to introduce a concept, not really to ask a question of the reader. State the concept directly:

         "To display something besides the welcome message on the reptile
         page, replace the *index_html* method in the reptile section with a
         more appropriate display method.  This still takes advantage of the
         zoo header and footer, including navigation."
   

   The result is a more assertive paragraph, one less sentence, and fewer words.

   This does not mean you should never ask questions, rather, you should ask questions to make the reader think about a possibility, or to engage their imagination, not to introduce a concept that can be stated directly.

7. Revise sentences that say little or nothing.

   The following sentences say little or nothing, and should be struck. What concepts they do present should be revised into surrounding sentences:

         "The Poll has a number of crisp abstractions."
   
         ShaneH (2000-11-01): This *does* have significance for the right
           reader.  Again, know your audience.
   
         "At first it would appear straightforward."
   
         XXX
   

ShaneH? (2000-11-01)

I believe this guide is useful for revision of documentation and should say so. The tone needs to encourage everyone, including unskilled writers, to simply start writing (assuming the documentation is part of a real project) and revise later.