Reference Manuals or, The Best Friend a Technical Writer Could Have

So I handed in some course material recently to a client and they passed it onto a customer. The response fro the customer was: "You didn't cover this" and "You didn't mention this."

So it was back to the usual discussion:

• Who do you think your audience is for this document? (the response is, usually, "Everyone")
• What do they do? (If the previous response was "Everyone" this is where the wheels fall off)
• How would the material you want to include help the audience do what they do? (And the response is often something like "Well, I think readers need to know this. Background, you know. General inforamtion.")
  

I shouldn't complain in this case, though: The customer really did have a pretty good idea of who the audience was and what the audience did. What they got stuck at was the "Well, I think they should know this" stage. They were getting pretty stubborn about it, too.

So we started listing off all the scenarios where the customer felt this document would be helpful to the audience. Again, to be fair, the customer did point out some information that I should have included to support a particular scenario (I had missed the scenario entirely and only included the rest of the information for the scenario because it overlapped with a bunch of other scenarios!).

But, other than that case, most of what the customer wanted to include wasn't relevant to any of the audience's scenarios. Usually, at this point, the client sees the light and moves on to complaining about other things (usually: grammar and vocabulary).

This customer didn't. They had a concept of their audience that reflected the customer's view of the information. The customer was passionately interested in this stuff and thought the audience would be too. They wouldn't recognize that the audience was only going to read what they absolutely needed to--what the audience felt they needed to know to get their job done.

Fortunately, I had a back up plan. "How about this? " I said, "Why don't we create a reference or a background document? We could send that out with the manual and the audience could refer to that. We could put this material in the reference manual." The customer bought into that.

There are, at least, two great things about a reference manual:

• Reference manuals are generally easier to write than a "real" document because a reference manual isn't driven by any scenario (heck--it frequently isn't read at all). You can just toss stuff into a reference manual and organize it using some arbitrary scheme (e.g. alphabetically)
  
• The customer usually runs out of buget/schedule before you get to the reference manual and you never have to write it all

So that's what we're doing (and I bet I never have to write it).


Reading or read

• The Torrents of Spring by Ivan Turgenev  
•  Myths and Legends of Russia by Aleksandr Afanas’ev