What to document
-
Runbooks? SOP? (cparedes: might be worthwhile even though we want to automate SOP’s away as much as possible - what should we check at 2 AM? What do folks typically do in this situation if automation fails?)
-
Architecture and design (cparedes: also maybe talk about why we choose that design - what problems did we try to solve? Why is this a good solution?) How to manage documentation
Documentation through Diagrams
Anecdote At one job we had a single network engineer. He had a habit of walking up to a whiteboard to explain something to the systems folks. He would proceed to draw what we considered a hyper-complex-looking diagram showing the current or future state of some networking solution. We could never keep his configurations in our heads like he did and he wasn’t always around when we had a question. One of us figured out that we should take a picture of the whiteboard after he finished drawing. These pictures went into the operations wiki. They weren’t beautiful but they saved us time when we could easily refer back to the pictures we took.
Diagrams don’t always have to be professional visio-quality to count as documentation.
Functional diagrams
Technical diagrams