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.

I lifted and simplified this layout Tom Limoncelli’s Ops Report Card section on documentation.

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

Pager Playbook

  • 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
  • Risks
  • Service Level Agreement (either real/legal or social)

Notes

  • Any notes about the service
  • Things that don’t fit well above
  • Future to do or improvements
  • Uncommonly needed tasks