The Problem of Documentation for Beginners

Who likes writing documentation? Very few.

But, in many fields, it can be difficult to get started because of information that is left out of documentation. When one does not know much in an area, it is very easy for a missing piece of information to make it difficult or even impossible to proceed. I had this problem recently yet again with a software package. The package has a lot of features, but we are having trouble getting them in use.

Even something is written down, it can be difficult to find when one does not know much yet in the area.

What often is missing is documentation for the documentation. This would be what one needs to know get started and where one should go from there.

I am quite prepared to put in my time studying, but all too often, I have no idea where to profitably begin. Even if I get a result, I, all too often, find that there were some key pieces of information that would have made it much easier to get results.

Throwing the manual at me is often of little good. If I do not know an area, then one of the things that I do not know is how to evaluate the important of data in the area. One manual page is much like any other. Knowing which are the most important for getting started is quite valuable information for a newbie.

If you are ever documenting something for a beginner to use, please put together something that a beginner can work with and have confidence that it will work. Examples really help a lot. Remember, too, that someone may be an expert in an area but still not be able to use what you are documenting.

An accountant will not automatically know how to use an accounting package. Even if that accountant can figure out some of it, the other part may be quite unclear. Ever wonder why some software features rarely get used? Who can figure out how they work?

So, when documenting, please write to your audience’s knowledge level, put in everything needed (including examples) to get things started, and point out where to go from there.

Then, maybe, you can document the advanced features.