Thursday, January 15, 2009

Multiple Audience Documentation

Due in part to my own memory (or lack thereof), I write a fair amount of documentation. And I make my team write a lot of documentation (so I don't forget what they tell me!).  Usually the things we write are fairly quick and easy:
  • workarounds to bugs
  • bug descriptions
  • quick guides for how to run scripts or configure tests
We're working on switching defect tracking systems (the old one no longer really meets our needs well), and needed to document that. What's interesting here is we have two audiences:
  • New users (new employees, possibly customers, etc)
  • People who used the old system (developers, support, etc)
One audience needs a fair amount of information. New users need to know what an "environment" is, or how we determine priority, etc. It's not an overwhelming amount of information, but it's not short. The other audience - existing system users - doesn't need all the same information. They already know how to set priority, for example. Instead, they need to know what's changing. What's different about the old and and the new system?

The obvious answer here is to write standard documentation: here's how to create a bug; here's how to resolve a bug. But... that's a turn off for your existing users.

It's insulting to be told something you already know. (After all, you're basically treating them like they're more ignorant than they actually are.) And what your documentation is doing is telling your existing users what they already know.

So how do you handle this?

The easiest way that I've found is to go on and do the documentation for your new users. Then add a section that describes the changes. This can be done effectively as a separate section ("Experienced users start here!") or as sidebars in each section. Think quick hits for your savvy audience, and then make them easy to find.

The point here is that you need to accommodate both audiences explicitly, not just write for the people who need the most information. It will make all of your users feel welcome, and that will make your documentation a lot more effective.


  1. Ever looked at Docbook? You can write the documentation in such away that the same data can be passed off to either a new user or an experienced user.

    I've been using it for on of my company's more complex products, and it allows me to diverge into docs for different end users (which have different customizations), support people, sales, etc...

  2. Yup - I really like Docbook. Most of what I did with it was producing online and paper help.

    I find it a bit of overkill for a quick workaround or a small doc like this, though.