How do you avoid that server documentation gets out of sync with the actual setup?

Frerich Raabe asked:

We have have reasonably good documentation for our environment (in AsciiDoc format) which recently allowed another person to recreate the entire setup from scratch in less than 30 minutes.
However, I noticed that after the initial setup, it easily happens that small changes done to the system (say: inetd gets disabbled, my IMAP server listens on an additional port for ManageSieve connections, a new router is added to the exim configuration) don’t end up in the documentation immediately (if at all).

My idea was to avoid this problem by (partially?) generating the documentation out of the configuration files and the comments therein – one way to implement this may be to put /etc and /usr/local/etc into some source code management system (say – git) and then run a script which regenerates the documentation on every commit. However, I’m not sure whether that would be overkill and/or too difficult to get right (after all, I don’t want complete copies of the source files in my documentation but rather just the diffs).

How do other people avoid that the server documentation gets outdated – is there a good way to keep them in sync automatically, or do you just have the discipline to update the documentation the same time you modify the system?

My answer:


If you only admin one or two small systems, setting up a large configuration management system like puppet or chef seems like overkill. (Though, if you plan to have more systems in the future, do it now!)

For a small setup like this, I’d recommend using something like etckeeper, a program which puts /etc into a git repository and provides a few useful functions, like doing an automatic commit whenever you install, upgrade or remove a package.


View the full question and answer on Server Fault.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.