Chapter 9. Documentation Guidelines

Table of Contents

1. Some antisocial English recommendations
2. Definitions
3. Tools installation
Docbook XSL Stylesheet
4. Handwriting for the manuals
Some Tricks
Docbook FAQ
5. Code documentation
Developer comments
Doxygen FAQ
6. References

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?