What should I document
We are told to document what we do. Alright, I admit it; I'm the one who keeps on about the need for good documentation. I'm a big fan of documentation and among my coworkers and clients, I've gathered a reputation for persuading, cajoling and hopefully encouraging people to write documentation.
In this article, I'm going to assume that you are (recently?) convinced that it's a good idea to improve your documentation; I'm not going to go on about why it's a good idea, but instead about what to write.
Scope
I'm talking about systems in an intentionally general way, including anything from a single instance of a piece of application software to a LAMP stack all the way up to a ecosystem of distributed systems and the multitudinous services that depend upon or are its dependencies.
Writing
Whenever you write anything, you want to keep the following questions in mind:
- Who will read it?
- What are they trying to achieve?
- What kind of background do they have?
Readers' Goals
How can we make it easier for the reader to achieve their goal?
- Operations goals (aka break/fix or meeting the customers' immediate needs)
- a reference that identifies common/serious failure modes and how to fix them?
- Which error messages can safely be ignored?
- Who are the stakeholders that should be notified in the event of problems/changes?
- Where does this system appear in a runtime dependency graph?
- Where to get more help?
- Licensing
- Engineering goals (or making the "world" a better place)
- Robustness
- Examining the dependency graph to analyse consequences of changes elsewhere or remote consequences of changes to this system
- Security analysis
- Load Balancing for redundancy/performance
- What's the mid-term/long-term plan?
Answer these questions
- What
- does the system do. This could (should?) be at several levels of detail. Emphasize what is special or different from the vendor manual or the standard setup.
- How
- is the system configured. This could (should?) be at several levels of detail, but not so deep as to be simply repeating the configuration files.
- Why
- was it architected this way? What alternatives were tried/considered?
- Who
- cares about the system? Who (or what system/s) uses it? Who maintains it? Who pays for it?
Extra Benefit
Writing is useful to the author, even if it's never read, because it's next best method of improving learning and really grokking it after actively teaching someone else. But really the point is to write documentation that will be used effectively.