DEV Community

Discussion on: I'm an ops person. Ask me anything!

Collapse
 
benaryorg profile image
#benaryorg

If by systems documentation you mean "documenting a setup, how it works, what each part/server does and so on", read on.

Examples of system documentation down well.

Assuming you mean "done well":

Building conventions is a great way to avoid the whole thing altogether.
Not that I particularly hate documentation, but if you're taught to build a simplistic demo-setup and can immediately recognise that pattern all over the infrastructure and work with/adapt it, that's a vital way to work.
If there's something new, a yet-to-be best practice or some old practice, then you need a place to stick that.
A large database that keeps metadata about machines (name: note to be confused with the hostname, patch information, arbitrary tags and such) is usually a good thing for stuff that needs to be documented for every single machine.
For everything out-of-place I found some sort of Wiki with a place that contains all of the specials quite neat.

Checklists for systems documentation preparation

We have a very nice document called a QA checklist.
After building a setup we check against that to see whether everything's there.
The QA is done by someone not involved in the setup process so that everything fishy/undocumented immediately pops out and can be documented.

Book you like that cover the subject (in whole or in part).

Sorry, still caught up with the Cthulhu Mythos Tales.