Signs of Triviality

Opinions, mostly my own, on the importance of being and other things.
[homepage] [index] [] [@jschauma] [RSS]

Writing About Writing

The following is a modified excerpt and summary of a draft of what will become the third chapter my book "An Introduction to Design for Professional System Administration". I initially did not include a full length chapter on documentation in my table of contents, but recently have come to the conclusion that that is in fact required: the basics of creating systems documentation are not covered in many other texts, and I've repeatedly obvserved in my class that students are simply not used to creating actually useful documentation.

The chapter will be titled "Documentation Techniques", and if you're interested in helping me review it, please let me know.

Chapter 03Good system documentation goes further than just providing manual pages for the tools we use. As we increase our organization's footprint, as we expand and scale upwards we are building more and more complex interacting systems comprised of hundreds of different software and hardware components, we employ increasingly elaborate and automated ways of operating these systems, influenced by larger and larger numbers of external factors.

It is unreasonable to expect the people building and operating these systems to remember how all the parts fit together, and virtually every single System Administrator will agree on the importance of high-quality documentation.

At the same time, however, few people actually go beyond the good intentions and pay more than just lip service to the old "document everything" mantra, mainly because many of us simply do not enjoy writing documentation, and are, cause and result at the same time, not particularly good at it.

Writing is communication. The motivation, purpose and effective techniques used in any kind of writing are entirely similar, which is why we can adapt elementary advise from any introductory class on writing.

First, ask yourself what the purpose of the documentation to be created actually is. Does it fall into the category of being a descriptive text (answering the question "What is this?"), an explanatory text ("Why is this the way it is?") or perhaps it is more instructional ("How do I do X?"). Keeping in mind your primary purpose can help you restrict scope.

Secondly, almost more of a platitude than a profound insight, know your audience. When we create system documentation, we usually target the following readers:

  • We write documentation for ourselves.
  • We write documentation for (other) system administrators.
  • We write documentation for (other) technical people.
  • We write documentation for all users of our systems.
  • We write documentation for interested people inside and outside of our organization.

The differences in target audience have a certain impact on how you would structure your documentation as well as, in some cases, implications on access control of the information in question.

Based on the above simple distinctions in target audience and purpose of the document, I have categorized the following different document types:

  • Processes and Procedures
  • Policies
  • Online Help and Reference
  • Infrastructure Architecture and Design
  • Program Specification and Software Documentation

Each document type is targeted towards different audiences and requires a different writing- or document style. You may create and use different templates for these different types in your information repository -- an excellent term used by Tom Limoncelli in "Time Management for System Administrators", one of the only books I've found that covers documentation techniques.

One of the main differences to creative writing is that our documentation is in almost all cases intended to be consumed online. Studies have shown that not all "reading" is equal: content consumed via a web browser, for example, is frequently only glanced through, skimmed over or otherwise not paid full attention to. When we read documents online, we tend to search for very specific information; we attempt to extract the "important" parts quickly and tend to ignore the rest.

As a result, online documentation needs to be much more succinct than information intended for actual print. (This blog post, lengthy as it is, is significantly shorter than the chapter will be in the book; the structure is different as well.)

Another major difference to other types of writing is that creating and maintaining system documentation is not a soletary task. Instead, you collaborate with your colleagues to produce the most accurate information possible, and allowing end users to update at least some of the documents you provide has proven a good way to keep them engaged and improve the quality of your documentation.

The requirements for a suitable information repository are:

  • allow for (simultaneous) distributed collaboration
  • include a revision history and the ability to roll back changes or merge conflicts
  • provide reasonably fine-grained access control
  • allow for links and references amongst documents within and outside the repository
  • provide search- and auto-generated index functionality
  • include support for different media types (images and diagrams, spreadsheets or other business reports, possibly videos illustrating the use of a tool etc.)

Finally, one more word of advise: even though at times necessary, try to avoid the use of too many diagrams or pictures. Instead, try to provide a verbal description of the network architecture. "A picture is worth a thousand words", right? Well, the problem is: if you need a thousand words to describe your architecture, it is probably too complex. We want to keep things simple, as simple as possible. You should be able to describe your network in a few simple sentences.

Keeping your content simple and to the point means that it is much easier to update when the network topology changes. Plain ASCII text has been good enough for every single internet standard from RFC0001 ("Host Software", April 1969) through RFC6578 ("Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)", March 2012) -- if your infrastructure looks more complex than the Internet at large... perhaps try to simplify and break out larger components into less complex blocks, individually documented.

Just remember that the easier you make it for yourself, your colleagues and your users to create content, to keep it up to date and to correct even minor errors, the better your documentation will be. And with good documentation come happy users, fewer alerts, less stress under duress and other sysadmin bliss.

April 2nd, 2012

[Achtung, Deutsch!] [Index] [Brilliant Ideas: BeerWare]