Chapter 9. Documentation Guidelines
Prev |  | Next

# Chapter 9. Documentation Guidelines

## 1. Some antisocial English recommendations

Here are the most frequent mistakes once seen in user documentation. A well written documentation makes the learning curve less steep for potential users and support the profesionnal look of the software.

Use a spellchecker. This finds words like "choosen", "choosed", "chosed" (the correct form is "chosen").

Do not repeat things when they are totally obvious. For instance, when there is a button "Add Server", do not write "To add a server, click on Add Server button." This is boring for the reader, who then pays less attention. Another example: "colorScale", documentation: "This is the color scale used". Here, the documentation brings no information.

English details (that the spellchecker will not find):

- "mouse button pressed down" and variants -> "click"
- no space before punctuations in two parts (i.e., as opposed to French, no space before ";:!?")

Writing good documention is hard, it requires adopting the reader point of view: which question does she have? what is surprising for someone new to Tulip? what will she chafe at?

Prev |  | Next
4. Integration in Tulip project | Home | 2. Definitions