Few weeks ago I needed to read the user manuals for software that was written just for internal company use. It was a nightmare. It is very often a pain to read documentation that was made for internal use.

Imagine Paul, he just entered joined the team, his first task is to produce the workload reports for the team, for doing this he’s got to use the internal tool, that was created ad-hoc few years ago. Nobody in the team is available to explain him how to create these reports, they all say: “have you read the manual?” or “read the manual first, then I’ll answer your questions”. The manual was written when the program was created and never update since. Paul can’t almost understand a single concept in it. The very first phrase in the manual is: “In case you need to create a report for a new week  [cut]“. After reading Paul is quite disconcerne: “In case you need to”? What is this program for? what does it do? How does it do it? Why do I need it?

The fact is that the developers may be very good at writing software, but when they have to write code they fall more often than not into some common errors that practically make the manual unusable:

1. Too technical
2. Lack of updates
3. Assume the reader knows exactly what they are talking about
4. No examples
5. The “it should look like” formula
6. No document owner
7. No version number

It’s easy to solve these problems. It doesn’t require too much effort, and it’s something very valuable to get.

1. There must be an owner of the document, responsible of keeping it updated
2. The documentation responsible must have some kind of training in making documentation
3. The document must be versioned
4. Must be written in proper english.
5. Good idea is to write documentation before coding.
6. Write the documentation in a way that it is interesting to read.
7. Help understanding with lots of examples
8. Keep the documentation up to date
9. Explain every concept, don’t assume the reader knows anything about the subject
10. Explain the goals, always say what you are going to explain before explaining it.
11. Do not assume the reader knows what you are talking about.
12. Say it, then repeat it, then say it once more.

I repeated few of them, it’s because they are important.

Share your good/bad experiences with documentation in the comments below.