If you've been around software for any time at all, you've encountered the type. You ask what seems to you as a reasonable question, and the belligerent sorts fall over themselves to be unhelpful; calling you lazy, an idiot, or worse, and telling you to RTFM. If you're lucky, they'll tell you where the FM is. If you're not, they'll tell you to STFW for it.
For those not up on the acronyms, RTFM and STFW stand for Read The Manual, and Search The Web, respectively.
The trouble is that there's a direct correlation between the probability that you'll be told to RTFM, and the probability that the FM is rubbish. That's because humility, patience and a willingness to help beginners go hand-in-hand with producing good documentation.
The burden falls on those of us within the software community to write a better FM.
For the last ten years or so, I've been involved in several efforts to write better documentation on several Open Source projects. I've noticed some trends in documentation. While some projects have stuck to the tried-and-not-so-true, RTFM, "the newbie is a loser" style of customer support, an increasing number of projects have moved to customer-centered documentation and customer-centered support.
If we want customers to RTFM, we are obliged to write a better FM.
I'm Not a "User"
Respect is very important. If you are unable to treat beginners with patience and respect, you shouldn't be doing customer support, or writing documentation. While there are places for banter and inside jokes, technical documentation is not one of them.
Thinking of your audience as customers, rather than as "users", or, worse yet, "lusers", will greatly influence how you write.
Listen To the Questions
While this may seem blindingly obvious, it's clear from the documentation of many products, and in particular their so-called 'Frequently Asked Questions', that they have no idea whatsoever what questions actual users of their product are asking.
To know what questions are being asked, you should frequent the places where these frustrated users hang out after not finding the answers in your documentation. These places tend to be web forums full of bad advice and broken examples. When you feel your irritation building, remember that they exist because your documentation wasn't filling the need, and so these third-party sites sprung up to fill it.
You will quickly find that they tend to be full of people asking the same questions, again and again, and getting a variety of answers of varying quality. It is now your job to make sure that the official documentation answers these questions correctly, showing best-practice solutions to the real-world problems, and makes them easy to find. Failure to do so simply drives people to these question-and-answer sites where they will continue to get bad advice.
Ask Smart Questions
Several years ago, Eric Raymond wrote a document about how to ask smart questions. While this seemed like a good idea at the time, it has since become a lengthy tome that no beginner will ever actually read, and which drips with condescension.
The document states three things:
- Try to find the answer yourself before asking.
- Provide all relevant supporting data with your question.
- If you don't understand the answer, it's probably because you're too stupid to live.
Points 1 and 2 are good, right and important. Unfortunately, point 3 colors the tone of the whole document. Indeed, the word "idiots" appears first in the second paragraph. Although it seems that Eric thinks he's being funny, instead he insults everyone who doesn't know as much as him.
Down at the very bottom of the document is a section titled "How To Answer Questions in a Helpful Way." This is the most (and perhaps the only) useful part of the document, and well worth reading.
While it is indeed important to ask smart questions, and not expect that someone is going to hold your hand every step of the way, as documentation authors, it's important to cast our minds back to when we first started--how lost we felt, and how we didn't even know what questions to ask. If that was too long ago, you can readily refresh your mind by picking a software product you're unfamiliar with, in a language you don't know, and trying to install it and get it running. It will all come back to you.
As Donald Rumsfeld famously remarked, there are also unknown unknowns, the ones we don't know we don't know. Start by assuming that your customer isn't an imbecile, but that they may not know what questions they should be asking.
Help your customers know what questions to ask by structuring your documentation in terms of how they are going to use it. Segment the documentation by audience (Developer, User, Administrator), and then further by task (Installation, Reporting, Upgrading) rather than in seemingly arbitrary groupings like "How-To" and "Other Topics".
No Stupid Questions
You've often heard it said that there are no stupid questions. While this is obviously false, much documentation seems to start with the assumption that all questions are stupid. There is a middle ground.
You must start by assuming that questions are smart and useful.
Frequently when I'm watching in an IRC channel, someone will ask "How do I do X?", and the immediate response is "You don't do X, you idiot! That's a stupid thing to do! Did your mother ever drop you on your head?"
Rather than treating them like a teenager, try to imagine that the person asking the question is a professional, like yourself, working on a project that might not have been their idea, but that nevertheless they need to get working.
Likewise, when writing documentation, keep in mind the real-world problems that are faced when using your product. Remember that not everyone has the in-depth knowledge of the inner workings that you do. And, most importantly, remember to treat your customers with respect, all the time.
In practical terms, this means avoiding words like "obviously", "simply", and "just", while providing many immediately usable examples with detailed explanations of each point.
Laziness, Impatience and Hubris
Larry Wall once declared that the virtues of a programmer are laziness, impatience and hubris. This is often taken as license to be a jerk. I would assert, to the contrary, that the virtues of a documentation writer are laziness, patience and humility.
Yes, it's important to be lazy. When someone asks a good question, answer them thoroughly, in exhaustive detail, and then publish the response so that the next time the question is asked, you can answer with a URL. Doing something well once beats doing it poorly, again and again.
You must be patient. Being impatient with a customer implies that you think they are either being intentionally obtuse, or that they are just too stupid to understand what you are saying. Being patient with them shows respect. The patient, respectful answer will stick with them, while the impatient rude answer will be remembered only as an unpleasant experience to put behind them.
And you should be humble. I find it useful to remember that the person I'm talking to is probably an expert on something of which I am completely ignorant. I also find it helpful to remember the first time I was asking questions, and the way that I was treated at the time.
