Re: Elements in a Tech Reference Manual

[Tim Altom <taltom -at- SIMPLYWRITTEN -dot- COM>]

Nancy, around here we have a simple answer to questions like these: Check
with your user and see what the user wants. And not just a list of what they
think goes into the manual. See what they'll be doing with it, under what
conditions, and for how long. Ask what isn't in other materials that they
need in this one. What problems will they be trying to solve with it? If
it's a true reference, then how will they need it organized? Will it need
extensive cross-refs? Full-text search? What categories of information will
you put things into?

When you have an excellent picture of entirely how this document is expected
to function, you'll have your answer from the best possible source. Try to
put yourself into the actual shoes of the intended user. And I mean to the
point of sketching the typical user and giving him a name. We're doing one
project right now for an expected user named "Ian." I could describe him
bodily, his background, his education, his on-the-job experience, his needs
and job stresses.

In short, nobody else matters, except perhaps the person with the magic pen
who signs off on things.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
http://www.simplywritten.com

>I've just been given the task of writing a technical reference manual for
an
>application. The system is a GUI interface that displays patient and lab
>result information that resides on a mainframe. Basically, it's the pretty,
>easy-to-use program that caregivers use to get read-only patient
>information; the actual info is entered via several different mainframe
>applications at our hospitals.
>
>I've always written end-user manuals; this is a first for me. What basic
>elements should be in such a reference? In the meeting today we discussed
>having sections on system architecture, troubleshooting, how the database
is
>organized, and something called "push printing" (which I'll learn about
next
>week). The development team doesn't really know what else they may want,
and
>I'm supposed to come up with a list.
>
>Any suggestions of what the typical structure of this type of book is would
>be welcome!
>

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=