Re: writing documentation
Technical documentation is part of the process. Here are some tips on how to make documentation less of a chore:
-
Document early in the process. I keep my docs as part of the source code in
wiki/, and update notes as part of the commit. -
If you’re not much of a writer, capture screenshots of the process instead. String them together after the fact. Helps capture statistics also.
- Keep it simple. Documentation is for continuity, not creative writing - zero points for marketing hooks.
- This is not a creative endeavor. I draft most documents with What, When, Why, How
- Drop unnecessary qualifiers like “IMHO”, “In my experience”, “You may notice”. Get to the point.
- Write for the reader’s benefit, not the writer (yourself).
- Runbooks should surface diagnosis steps on the top. First responders can triage an ongoing incident within minutes.
- Incident Reports should headline with an executive summary, incident status and root cause. All stakeholders including non-technical units can understand the impact of the incident and contribute to post mortems easily.
- Project documents should prioritize flow and architecture diagrams. Establish a foundational understanding of the project for cross collaborative units e.g. Product <> QA, QA <> Dev, Product <> Design, Dev <> Ops before diving into individual details.
Remember: Documentation should be simple to write and read. A consistent, straightforward practice of documentation will save hours of knowledge transfer later and prevent wasted minutes during an incident.