Actions: | Security

AllGoodBits.org

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've (recently?) been 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.

Scope

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 federated authentication/authorization ecosystem and the multitudinous services that depend upon or feed it. I'm largely not talking about documentation for end user/desktop support.

Writing

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.

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

What
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.
How
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.
Why
was it architected this way? What alternatives were tried/considered?
Who
cares about the system? Who (or what system/s) uses it? Who maintains it? Who pays for it?