RE: Writing first user manual. Advice?

[Geoff hart <ghart -at- attcanada -dot- ca>]

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