- 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.