November 20, 2014
Documentation is every IT professional’s job. I keep a 3x5 notecard with a generic layout I use to write documentation and all of my IT related stuff follows this pattern. I’m actually tired of keeping up with the card, so I’m going to put it here.
Overview or Summary
- A summary of what this is.
- Where does this service live?
- Why do we need it?
- Upstream documentation
- Design (Perhaps its own section outright)
- Diagrams of logic or data flow
- Other moving parts that make the whole
- Subject Matter Expert contacts
Common Tasks or Process
- Common tasks needed for care and feeding.
- If this is a documented process that process, step by step, goes here.
Deployment or Building
- Do we build the software locally, how do we do it
- How do we deploy more of these machines or replace busted ones
- Where are our configs in Puppet/Chef/Ansible
- Hardware Requirements
- How might the system fail?
- What does failure mean?
- What risks do we run?
- What to do to restore each service or part
- What side effects happen when specific parts are down or malfunctioning
Disaster Recovery Plans
- How is (or isn’t) this system recoverable from a disaster situation?
- What disasters have we planned for?
- HA plans can fit here too
- Steps that need to happen to recover
- Service Level Agreement (either real/legal or social)
- Any notes about the service
- Things that don’t fit well above
- Future to do or improvements
- Uncommonly needed tasks