Have you ever read a technical document and gotten overloaded on technical details - but failed to understand the product's basic operation?

Technical documents should be constructed like a funnel. First the overall purpose (where does this product fit in the world?) should be discussed. Then the author should gradually bring the reader's focus into the product's inner workings and finally the most minute technical details can be discussed. If this gradual narrowing of focus (the funnel) is followed by the author, it provides a firm context for the reader to understand how and why a product works.

All too often, software technical documentation focuses only on how to enable/disable a feature on a program without explaining what that feature does. The presumption is that the reader already knows why to enable or disable that feature. The rest of us are left in the dust.

Technical documentation has a dual role. It has to explain novel features that sometimes use newly coined terminology.  But is also has to function as a reference manual to prompt casual users which controls are which and how (and why) you enable/disable that novel feature.

-Don Burtis