The Secrets of  Good Documentation

 

The secret to producing good documentation is to first create a mental model in the reader's mind to act as a framework on which to hang all of the subsequent information that you tell them and that they infer.

 

If the reader lacks a valid mental model, or the one you create is incomplete or inaccurate, you may force the reader  to construct his or her own model on the fly, based on ignorance and preconceived notions. The new information you impart will then force the reader to dismantle an existing mental model -- not something that we humans do easily.

 

But with an incomplete or inaccurate mental model, and given they don't yet understand the topic you are trying to explain, the reader's mental model is doomed. Worse yet, as you give them additional (and accurate information, they will try and hang that information in rational places on their model (and there may be no such rational places). You can tell this is not going end well, right?  Dollars to donuts, this information is either going to be misconstrued or simply not understood and greeted with a "huh?"

 

Documentation must only tell the reader what they need to know and why they need to know it,  rather than be a brain dump of what the author knows.

 

Furthermore, good documentation must anticipate the reader's primary, secondary and perhaps even tertiary questions. (You say I must do X. Why? What happens if I don't? What are the unintended consequences of doing/not doing this? Who the hell was Rhonda the Immortal Waitress?) The writer makes assumptions about the level of prior knowledge of the reader at the risk of losing the reader's comprehension.

 

Is good documentation hard to create? Naaah. You just have to stare at your computer screen until beads of blood appear on your forehead. How hard can that be, eh?