Basics of Documentation Style
Prev |  | Next

## Basics of Documentation Style

Most people have never enjoyed reading a software manual, and they probably never will. Many times, they'll read the documentation only when they run into problems, and they'll be frustrated and upset before they even read a word. On the other hand, some readers will read the manual all the way through, or at least look at the introduction before they start. Your document might serve as a reference for an expert or a guide to a beginner, and it must have enough depth to satisfy the first without overwhelming the second. Ideally, it will serve beginners as they become experts. Remember, your goal is to produce complete, intuitive and clear documentation.

In order to write useful documentation, you'll have to know who your audience is likely to be. Then, you can look for the problems they're likely to run into, and solve them. It will also help if you focus on the tasks users will perform, and group features accordingly, rather than simply describing features at random.

### Planning

Begin documenting by learning how to use the application and reading over any existing documentation. Pay attention to places where your document will differ from the template. It may help to develop a document skeleton: a valid XML or SGML document that has little or no content. For very large applications, you will need to make significant departures from the templates, since you'll be using the `<book>` tag instead of `<chapter>` or `<article>`.

### Achieving a Balanced Style

Just as you need to juggle expert and novice readers, you'll have to juggle a number of other extremes as you write:

- Documents should be complete, yet concise. You should describe every feature, but you'll have decide how much detail is really necessary. It's not, for example, necessary to describe every button and form field in a dialog box, but you should make sure that your readers know how to bring up the dialog and what it does. If you spend fewer words on the obvious, you can spend more time clarifying the ambiguous labels and explaining items that are more complex.

- Be engaging and friendly, yet professional. Games documents may be less formal than productivity application documents (people don't use games, they play them), but all of them should maintain a standard of style which holds the reader's interest without resorting to jokes and untranslatable allusions or puns.

- Examples, tips, notes, and screenshots are useful to break up long stretches of text, but too many can get in the way, and make your documents too choppy to read. It's good to provide a screenshot of any dialog windows a user might run into, but if a dialog box has several tabs, it's not usually necessary to have one for each.

- The GDP strives to have all of its documentation conform to certain standards of style and content, but every document (and every writer) is different. You will need to use your judgement, and write documents to fit with the rest of the project, without compromising the individual needs of your subject, or your own individuality as a writer.

### Structure

In general, you won't have to worry too much about structure, because the templates provide you with an excellent example. As a general rule, try to follow that structural example. That means using links, hierarchical nesting, and, if necessary, a glossary or index. You probably won't need to use every available structural tag, but take advantage of what DocBook provides you.

As to linking, there's some disagreement about whether to use `<xref>` `<link>` when you make links within your documents. You'll have to decide, based on the different ways that they are presented in output, which is more appropriate given the context. Regardless of which you use, you should not forget to use them. Help your readers find information that relevant to the issue at hand.

The table of contents will be generated automatically, but you will probably have to develop your own index if you wish to have one. The Nautilus Help Browser will have new, and currently unknown, indexing capabilities, so index style and structure are still under discussion. The GNOME User's Guide will contain a glossary in its next versions; unless you're writing a`<book>`, it will probably be best to contribute to that rather than developing your own.

### Grammar and Spelling

Nobody expects you to be perfect; they just expect the documentation for their software to be error-free. That means that, in the same way that developers look for bugs and accept bug reports, writers must check for errors in their documents. Poor grammar, bad spelling, and gross technical errors in draft documents are fine. However, if those problems show up in a "real" release, they can count against the credibility of GNOME and Linux. They'll also make you look bad.

There is no substitute for a human proofreader; use a spell-check program, then read it over yourself, and then find someone else to help you. Other GDP members are, of course, willing and able to help you, but non-writers are often at least as helpful.

Proofreading documents is both a also a good way to familiarize yourself with documentation, and it certainly makes you valuable to the GDP. Help other writers proof their documents, and they will help you with yours.

Prev | Up | Next
Referring to Other GNOME Documentation (coming in GNOME-2.0) | Home | Teamwork