Treating Documentation as a Product
5 days ago
- #engineering
- #product-development
- #documentation
- Documentation should be treated as a product with the same level of ownership, rigor, and iteration as any other product.
- Design documentation by considering the audience, their knowledge gaps, and the paths they will take.
- Documentation must cater to multiple audiences, including new engineers, experienced engineers, integrators, DBAs, API consumers, architects, support engineers, and AI tools.
- Keep documentation close to the codebase to prevent drift and ensure it remains the authoritative source of truth.
- Measure documentation effectiveness using real impact metrics like user drop-off rates, bounce rates, and support ticket causes.
- Build a documentation system, not just pages, including information architecture, naming conventions, templates, and versioning strategies.
- Continuously iterate and refine documentation to maintain clarity and relevance.
- Engineers must actively participate in documentation to ensure its quality and accuracy.
- The WriteTheDocs community has long advocated for treating documentation as a product, and with AI consuming docs, the stakes are higher than ever.