Documentation is the long-term memory of your organization, the tool through which knowledge & process can be iterated on, and the evidence that change needs to be made. Diataxis is a framework through which effective documentation can be created.
Why Document?
Documentation is the long-term memory of your Organization
The Second Brain system applies to teams and organizations just as much as it supports an individual, by leveraging digital tools for long-term memory.
Documentation supports Iteration on Knowledge
People have finite cognitive resources. It is significantly easier to iterate on a document to improve a process.
Documentation informs Organizational Decisions
A document describing how to add a new API can be a powerful justification for refactoring the API process.
For example, imagine it takes 12 steps and consumes two hours of an engineer's time each time you add a new API.
Documentation reduces the strain on the engineer, but also makes what was previously invisible, visible.
Framework: Diataxis
Diataxis is a framework for effective technical documentation.
Tutorials
A tutorial support learning specific concepts and are typically built by experts.
How-to Guides
How-to guides support achieving specific results and have an end goal in mind.
Explanation
Explanation supports reflection and deeper understanding.
Reference
Reference guides are technical descriptions of capabilities and provide information.