Building SaaS - Techincal Documentation
Must Read or Watch
Investing in Internal Documentation: A Brick-by-Brick Guide for Startups
Someone needs to be responsible. It has to be their job. Lead by example.
- Recap regularly.
- Get existential. "What did you learn recently? What is your interpretation of current company goals? What recent shifts have you made to the strategy?"
- Focus on quality, not quantity to set the bar.
Try to identify the top five to 10 technical topics that engineers are struggling with the most and invest in those. (use analytics on internal search)
Glossary: “Every company has their own terminology and vernacular for systems and services. Creating a glossary is such a simple way to create a source of truth for important definitions.”
Five documentation buckets that exist at most decently-sized companies.
- Onboarding documentation
- Task-based documentation: For example, instructions for your internal users on how to build a new endpoint, integrate with an interface, or use a new feature.
- Runbooks: How to perform a set of tasks in a specific order to perform a common operational task like spinning up a new server or resolving a common error.
- Architecture and design documents
- Wiki-style team documents: Including meeting notes, memos, musings, proposals.
Level up with landing pages
- Backend development
- Frontend development
- Security
- Metrics and Monitoring
- Storing and managing data
Pitfalls to avoid
- Forgetting the Past: No version control of the documentation
- Sad Kid On Show and Tell Day: Don’t describe any use cases or real-world examples or provide any sample implementations.
- Echoes: Little bits of information that are repeated and/or mutated across several documents, rather than stated once and referenced.
- Dependency Hell: Screenshots, links to 3rd party
- Big Ball of Mud: Adding Content as fast as possible with no structural intent.
- The Guru: A single person that controls all docs
Read more at 4 Common Antipatterns to Avoid in Your Documentation and Docs Antipatterns (Part 2).