curse of knowledge : Java Glossary

Have you ever read documentation that you could not make any sense of? Documentation ripe with information on obscure options, but that gave you no idea what the program was for or how to use it in the ordinary cases? The problem is the curse of knowledge. The author knows too much. He cannot put themselves in the place of a newcomer. To him everything is obvious, so does not need to be stated. Only thing unobvious to him rate exposition. The classic examples are typical Unix man pages that treat every one of 50 options as equally important, written in a BNF (Backus-Naur Form) dialect without examples.

Even a precis often presumes the reader already knows what the program is for. The error the author makes is presuming the reader is just as much of an expert in vocabulary as the author.

Sometimes the author gives too much detail or nitpicking exceptions and hides the essential message.

How can you, as author, avoid these problem?

• Get somebody else to write the documentation, asking questions of the author.
• Get virgins to read the documentation and ask questions about what they don’t understand.
• Get the author to watch virgins using the program and reading the documentation, the author asking the virgins what they are thinking, to figure out what is confusing them.
• Write the documentation and let is age for a year, then come back to it cold and try reading it to see how much of it makes sense and if it answers the questions you need to know to use the program.