Why no one reads your product docs, and how to fix it

Introduction

People don’t avoid reading your product documentation because they're lazy. The reason no one reads your documentation is that it wasn't designed to be useful. To fix this issue, it's crucial to think of documentation as products with users, use cases, and measurable outcomes.

Core Documentation Failures

1. Overgeneralization: One document tries to serve multiple stakeholders with different needs and attention spans.
2. Overengineering: Complexity in formatting, tool migrations, and structure makes the content unreadable.
3. Oversharing: Instead of focusing on what matters, the document becomes exhaustive but not insightful.

Providing Multiple Zoom Levels

• Executive Summary: What's being built and why it matters.
• Deep Technical Spec: For implementation details.
• Design Artifacts and UX Notes: Providing context and cohesion.
• Open Questions and Tradeoffs: Encouraging transparency and collaboration.

Treating Docs Like Usable Interfaces

1. The Five-Second Rule: Ensuring quick understanding of the document's purpose.
2. Selecting the Right Tool: Choose tools like Notion, Coda, Google Docs, Linear Docs, or Confluence intentionally and stick with them throughout the project.
3. Using Good Templates: Templates like those provided by the Good Docs project help create clear, user-centric documentation.

Conclusion

• Clarity should be a design principle in documentation.
• Treat product docs as part of the product and design them for the humans who will use them.