I am at the beginning of a new project right now. Since it involves a lot of stuff I don't know nothing about I have to do a lot of reading. And while I was reading these pieces of documentation with varying degrees of quality I realized that there are 4 kinds of documentation.

The swedish rack construction manual: The creation process for this kind of document is well known. You take an average woolen pullover or an employee of comparable intelligence and let him explain the process of constructing a rack to another employee who will write it down (in swedish) this gets translated by a Japanese to English and the final construction manual gets added to boxes containing the pieces for a sofa.

These kind of manual only serve as an example of how not to write documentation. They are just wrong. Useless. Rubbish.

The tome of ancient knowledge: This contains a lot of wisdom. But it is old. It is long-winded. All the references lead to webpages long gone. The language used is arcane. Sprinkled with injections of utter madness. But it contains the rituals necessary. If you only follow the rituals IT will happen. Nobody really knows what IT is, or if IT is something to look forward to. Or if IT means that the stars will align and the world comes to an end. You will never know since the smallest mistake in the rituals (i.e. configuration files, script executions and sacrifices to the Great Old Ones) will just result in some obscure call stack and possibly madness. There is no reason given why you have to do the rituals. There is no reason given, why you have to do them this way. Just follow along. Just type rm -rf /

The revel model construction manual Do you know these plastic models? You brake all the pieces. Glue them together. Paint them. Put some stickers on and end up with a cool model of some fighter aircraft or battle ship. Only problem is: The instructions are in the wrong order. You get advised to glue the top piece of the fighter on the bottom. And when you are done with that you turn the page just to read: "But before that insert the transparent window pieces in the inside" which of course you can't anymore. So you either claim that real fighter pilots don't need windshields or you buy another model and try again.

And finally there is the manual. It is simple. It tells you what it is all about. Why you need it, what you have to do, and what is going to happen. In the right order. It even tells you about the mistakes you are going to make and how to fix them. It has a glossary which explains all the terms and an index to find them in context. You understand the structure of it after a quick glance at the table of content. You just follow the steps, read the explanations and are done in no time.

Unfortunately I haven't found the manual yet.