Actions: | Security

Navigation: Home | Services | Tools | Articles | Other

What should I document

We are told to document what we do. Alright, I admit it; I'm the one who keeps on about the need for good documentation. I'm a big fan of documentation and among my coworkers and clients, I've gathered a reputation for persuading, cajoling and hopefully encouraging people to write documentation.

In this article, I'm going to assume that you are (recently?) convinced that it's a good idea to improve your documentation; I'm not going to go on about why it's a good idea, but instead about what to write.


I'm talking about systems in an intentionally general way, including anything from a single instance of a piece of application software to a LAMP stack all the way up to a ecosystem of distributed systems and the multitudinous services that depend upon or are its dependencies.


Whenever you write anything, you want to keep the following questions in mind:

Readers' Goals

How can we make it easier for the reader to achieve their goal?

Answer these questions

does the system do. This could (should?) be at several levels of detail. Emphasize what is special or different from the vendor manual or the standard setup.
is the system configured. This could (should?) be at several levels of detail, but not so deep as to be simply repeating the configuration files.
was it architected this way? What alternatives were tried/considered?
cares about the system? Who (or what system/s) uses it? Who maintains it? Who pays for it?

Extra Benefit

Writing is useful to the author, even if it's never read, because it's next best method of improving learning and really grokking it after actively teaching someone else. But really the point is to write documentation that will be used effectively.