RE: Writing first user manual. Advice?

Subject: RE: Writing first user manual. Advice?
From: Geoff hart <ghart -at- attcanada -dot- ca>
To: "Techwr-L (E-mail)" <techwr-l -at- lists -dot- raycomm -dot- com>, "'mhbartel -at- ThoughtWorks -dot- com'" <mhbartel -at- ThoughtWorks -dot- com>
Date: Fri, 21 Jul 2000 08:46:35 -0400

Meg Bartelt is <<...about to start writing a user manual for a huge leasing
application. I'm relatively new to the technical writing field and have had no
experience with user manuals (other than using them).>>

That's by far the best experience anyone could have. What do you like about the
manuals you've used? Do that in your own documentation. What do you dislike
about the manuals you've used? Don't do that in your documentation. Approach
the manuals with a slightly naive eye, paying more attention to your reading
experience than to the actual results: what aspects of the docs help you
accomplish a task, and what aspects interfere with completing the task? Ignore
actually trying to complete the task for the moment, since we'll assume, for
the sake of keeping this message short, that you are going to test your writing
later to ensure that people can actually do what they want to do by following
your instructions.

<< Does anyone have any advice for how to approach this task? Should I just
look at the organization of existing good manuals? Is there a formula?>>

Starting with successful manuals is good, provided it's only a start. Each
product will have a slightly or dramatically different audience, and thus, a
different required approach. But all good manuals tend to include the same
sections (e.g., tutorials, references, task-based instructions, glossaries,
indexes), so knowing what these sections are is a good starting point. Next,
take some time understanding your audience: who are they, and what do they want
to do with the product? If you can actually talk to the audience or people who
work with them, such as trainers or tech support staff, you'll get a much
better idea of who you're writing for. (If not, put yourself so firmly in their
shoes, mentally speaking, that you get blisters in the same spot they do; you
want to understand what they're feeling when they sit down by the keyboard and
want to start using the software.)

Start with broad categories (e.g., "printing reports") and break these down
into more details (e.g., formatting reports, preparing summary vs. detailed
reports, producing online vs. onpaper reports). Now impose a logical order on
the broad categories, and on the detailed tasks within those categories. That's
both your table of contents and your homework list. <g> Review that list with
the developers before you begin to make sure that everyone agrees on the final
goal, and that you haven't missed anything. While you're at it, get on friendly
terms with the developers; you'll need them when you encounter the inevitable
questions about how things work, and the easier it is to drop in on a developer
and chat, the easier it will be to ask questions related to annoying things,
like work. If you can't actually befriend them, at least get to the point where
they don't groan when they see you coming down the hall.

Start writing! (Focus on the modules that are complete, or nearly so, and leave
the ones that are still evolving rapidly until later, when they become stable.
That means less reworking of material because the underlying software changed.)
If you have the luxury of actually working with the users, test your first
efforts at documentation with those users for a reality check and to make sure
you discover mistakes early and don't keep repeating those mistakes throughout
the process; if you only have to fix a problem of style or approach or content
or detail or whatever once, you'll be much more productive than if you make
that mistake everywhere and have to go back and fix it each time.

That's about as close to a formula as you're going to get, which is a good
thing. If you want to work by formula, write for Hollywood, TV, or Harlequin
Romances <g>, not for product users. Since you don't, welcome to the wild world
of software docs!

And most important of all: since you're new at this, you've got a lot of room
to ask stupid questions. I've been doing this too long, so I don't have that
luxury any more. <g> Pop in on techwr-l whenever you have a question; in a year
or so, you'll have used up your quota of stupid questions, but until then,
you've got carte blanche to bend our ears.

--Geoff Hart ghart -at- netcom -dot- ca
"Most business books are written by consultants and professors who haven't
spent much time in a cubicle. That's like writing a firsthand account of the
Donner party based on the fact that you've eaten beef jerky."--Scott Adams, The
Dilbert Principle

Previous by Author: Re. Documenting code?
Next by Author: Making Word documents dead-only?
Previous by Thread: Re: Writing first user manual. Advice?
Next by Thread: Re: Recruiting Story

What this post helpful? Share it with friends and colleagues:

Sponsored Ads