![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
technical writing 201
Learn the domain. You should achieve basic competence in whatever it is that your readers will be doing when consulting your manual. If you're documenting a type of tool that you've never used -- CAD tool, machinery, API, or whatever -- then you're not going to have very good insight into your readers' needs. You don't have to be a programmer to write API documentation or a civil engineer to document a CAD tool or a medical doctor to document an X-ray machine, but you should try to learn enough about the domain to (1) understand what people tell you needs to be in the manual and (2) ask intelligent questions. If you're going to be in a particular domain for the long haul (you're not just a contractor who'll be gone in six months), try to get your employer to send you for some training.
Think about the forest and not just the trees. I've seen a lot of software documentation that just walks through the menus, saying fairly obvious things about each available command. Most people, however, don't sit down with an unfamiliar piece of software and ask "how do I use such-and-such feature?". (Frankly, if they're asking about a feature by name, they're probably going to just try it rather than consulting the manual.) People are using the product because they have some problem they want to solve or some task they need to accomplish.
It's not just software, of course. I once bought a drill that came with extensive documentation about charging the batteries, changing drill bits, varying the speed, and so on -- walking through every movable part -- but never actually said anything about drilling through different materials (is wood different from plaster or brick?), or how to recover from a problem such as getting stuck in a knot, or how to avoid strain on my wrist from the vibrations of a power tool.
To pick something familiar, let's say you're documenting a word-processing application. Your users probably want to know things like how to assemble templates or styles, how to structure large documents, how to set up generated fields like the TOC, index, and headers/footers, how to interoperate with other tools (import and export), and so on. I'm just picking tasks here; you can name twenty more without much difficulty. The point is that they don't go in asking things like "how do I customize the font on a paragraph", at least not initially. Don't get lost in the forest of specific options and commands; give them some higher-level guidance, especially for complex applications.
If you found yourself ready to argue with me in that last paragraph, good. That brings us to:
Think about different needs. A new user needs different things from someone who's already proficient with another tool, and he in turn needs different things than someone who's pretty fluent with this tool but needs to look up one obscure detail. Sometimes the answer is different documents -- a guide and a reference manual, for instance. Sometimes the answer is to provide different paths through the single document set -- the command index that's separate from the concepts index, the overview chapter with many cross-references into the rest of the material, and so on. Some of this depends on whether you're writing a hundred pages or a thousand, of course, but in general, if you keep in mind that people will need to find different information at different times, and you address that need, you're doing well.
Be creative. Not necessarily in the writing itself -- different organizations have different levels of tolerance for that -- but rather in approaching the task. Imagine yourself as a user, the more anal-retentive the better. What things might you try and what surprises are waiting for you? What limits might you push? Especially if you are writing something like an interface definition, you need to be as specific as you can be and anticipate the "what if I do this?" questions.
Your quality-assurance people have the same problem, by the way -- they have to come up with plausible scenarios by which people might break the tool. Team up with them; you can help each other out.
Use the tool. Follow your own instructions, but also explore it and see what else it can do. Are there features that your developers forgot to tell you about? Does it really work the way they said it does? Don't assume that the information you need will come to you; you should take an active role. If you can talk with people who've actually used the tool (and who aren't your developers), so much the better -- but often the users are out of reach, at least initially.
Write clearly and precisely. So far I haven't said anything about the actual writing. Yes, you should write in complete sentences that are grammatically correct and not confusing, but it's more than that. Use domain terminology carefully, and be mindful of words like "always" and "only" and "may" and "should". (I hate the word "should" in technical documentation, except in the case where the document is giving me advice about how to do something. What does it mean to say "the tool should do such-and-such if you do X"? Are you guessing, or is the tool non-deterministic?)
Don't use a paragraph where a sentence will do or vice-versa; learning how much you need to say is part of the education process. (Who are your readers? What do they already know?) Too much documentation is every bit as much of a problem as too little.
Talk with your peers. If there are other writers at your company, talk with them about what they do and what tricks they've learned. If there aren't, see if there are local meetings (formal or informal) where your peers from other companies show up. Join mailing lists. (Techwr-l is good.)
I'm not trying to scare anyone off, nor am I saying that you need to
hit all of these points right out of the gate. It takes a while to
learn not only a particular domain but the craft of technical writing
itself. These are things I think you should be thinking about.
You might also be interested in an entry I wrote a while back about what makes a top-notch programming writer.
no subject
And, a story to illustrate another point. I was once on a QA team that had a hideous development team to work with. "QA is a waste of my time. I don't write or talk to you people." We had to test the product (not knowing much, and not having documentation or source code. Nevertheless, we had a certain amount of proficiency.
It was an in-house tool. Someone had to train the users in it. Of course, Mister Don't-Waste-My-Time wasn't going to do it, or let his staff do it.
QA had to do it - and the customer was not happy with the result. "Why does it work this way? "Why not do it that way? Why isn't it organized this way? We don't do things this way, why is it this way?"
Eventually, my partner Chris (who was leading the seminar) gave a woeful sigh, a sad look, and said "Sorry. I'm not so good with the why questions."
Sometimes the documentation needs to be able to answer the why questions. :-)
no subject
True. A manual can't answer all the questions any user might have, but the more aware you are of the issues, the better a job you'll do. For example, it wouldn't be unreasonable for the documentation of a power tool to throw out some hints about how such a tool is different from the corresponding hand tool. A note in the section on using the drill to drive screws saying "here's how to not injure your wrists from the kick" might not be out of place.
Sometimes the documentation needs to be able to answer the why questions. :-)
Definitely. In particular, if you can teach your users the model, they'll do much better than if you just do a data dump. People can make inferences based on a model that they can't make from a collection of trivia. You should be teaching people how to really use the tool, not just how to push the buttons. And that requires some rationale.
no subject
The model is key. I have always wanted a scaffold of knowledge I can hang my knowledge on, or a growing sense I can anticipate what the software will do, because it'll do the same thing everywhere.
As a QA droid, sometimes I can even MAKE the software have that model and be consistent. :-)
no subject
Models: there's nothing worse than a tool that seems to be random or arbitrary.
As a QA droid, sometimes I can even MAKE the software have that model and be consistent. :-)
I've sometimes had success in telling developers "look, I'm really having trouble here, and I fear I may write a description that makes it sound like our developers don't know what they're doing, and clearly that's not correct so could you help me out with the big picture here?". Sometimes that help comes in the form of a change to the product, which is often the goal. :-)
no subject