Classic Documentation Problems and Solutions

Any documentation is very advantageous to a spoken word because it scales, it’s searchable, and it can be edited and versioned.

Here I list common problems and solutions for technical documentation:

• It’s complicated. Avoid cliffs of understanding, build a ramp for your audience. Split documents into categories and try not to mix them (tutorial, reference, explanation, requirements and so on). Read “Elements of style” or “On writing well”.
• It’s big. Make it easy to navigate documents. Place an emphasis.
• It’s hard to see the big picture. Draw the big picture before diving into details. Draw lines between components, they’re as important as components themselves.