Thursday, December 22, 2011

Describe the Unusual

Documentation is a part of my job, like many engineers. I write documentation for end users, training material, documentation for other developers (API docs, anyone?), bug reports... all sorts of things. And like many documentation creators, I can talk for a long time about some of these things.

Saying too much is a very good way to frustrate your audience. They don't want to know everything; they can't absorb it all and they lose the important parts. So follow the cardinal rule of documentation:

Describe the unusual.

Let's assume for the moment that documentation is about describing interaction. It attempts to explain to the reader how to successfully work with the system - whether that interaction is through an API, a GUI, or whatever - and how to understand what the system is doing (i.e., error states, message meanings, etc).

Describing interactions is a huge thing, which is why it's so easy to write a whole lot of documentation. But that's the wrong thing to do. The truth is, most of the time you can assume some basic knowledge, and just describe what's different.

For example, I'm working right now on a logging module for a system. The system right now does ad hoc logging; each component logs in its own way. My logging module will provide centralized logging so we get consistency in log level, storage location, format, etc. When I'm documenting this, what can I assume, and what should I write about?

My audience is other developers who work for this company. They pretty much understand the system, the language, and general development concepts. Great!

So I describe the things that are unusual:

  • instantiating this (custom) logger I wrote
  • requirements around uniqueness and sharing of loggers (class instances)
  • whether it is thread safe (yes) and process safe (no)
  • deployment requirements and the configuration format, for the IT guy
  • log size and rotation rules, which I got from the IT guy
I don't describe the things that developers generally expect from logging:
  • the existence of log rotation and aging
  • when to log at various levels (DEBUG vs INFO, etc)
  • the format of the log entry
I can skip what people already know, which makes the documentation much shorter and makes the important parts more readily apparent. It's easier for the consumers to read and much more likely to be actually useful.

So when you have to document something, whether it's a multi-day tutorial or a simple comment describing how to use a method, focus on the things that make it unique. Describe the unusual.


  1. Very interesting, Catherine! I'm curious if you have any publicly accessible examples of your documentation for engineers vs. users that you could share.

    Finding where that "just enough" point is in any documentation is so contextually dependent on audience, interface & subject that it can easily be a large point of contention.

    I'm curious how you find that point for the things you are working on. Do you just have a sense of it based on your interaction with your customers? Do you build in feedback mechanisms so you know where your efforts fall short?

  2. Good question - it's hard to get the right amount of documentation. I'm afraid the docs I have been doing are proprietary, but I'll see if I can find a public example that's not an old blog entry!

    As for finding the right point, that's something that takes time to learn. A lot of it comes from asking myself explicitly, "for whom am I writing? What does he know? What doesn't he know?" I try to have a specific person in mind, even if that person is a hodgepodge amalgam of many people, because then I can say, "well, does Fred know how to log in to the wiki? Yes, so i don't have to describe that, just tell him to do that." It's a little like using personas for design or testing work, really.

  3. Thanks Catherine! Agree! In my experience, use of personas in documentation is very similar to that recommended for design work. In fact, it's typically a recommended practice in most t-pubs theory (audience analysis distilled into usable personas to write against, etc...)

    In your work, do you use a formal topic-based writing approach? What about your documentation tool chain? I'd be really interested to hear more about what practices you've adopted at Abakas!