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.