technical writing 201

[cellio]

Someone recently asked me if I have any advice for someone at his first tech-writing gig. Asking me quesions like that is sort of like dangling tuna in front of the cats. :-)

Comments

[cellio]

That manual was about "this drill", not about drilling, dear. :-)

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.

[cellio]

The power drill led me to wonder about the feasibility of tasks I never would have attempted with a hand drill. (For example, drilling into a brick wall.) The spec sheet offered me some measure of power (probably horsepower), but I didn't know how to translate that into "things I could reasonably apply this tool to". That's my failing, of course, but perhaps not complete idiocy.

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

[jducoeur]

Thanks much -- I've passed on a pointer to this entry...