Re: Advice on User's Manual

Subject: Re: Advice on User's Manual
From: Diane Peters <dj -at- IBAPAH -dot- RAXCO -dot- COM>
Date: Fri, 1 Dec 1995 16:21:55 -0700

Suzanne,

Hi, I haven't been doing technical writing for very long (just over a
year), but I used to work from engineering specs to write test scripts
and test plans for a quality assurance team, and now I am a technical
writer who uses engineering (functional) specs--among other things--to
write software user manuals. So, I'll share with you what I do know.
BTW, the above experience was for two different companies with very
different ideas about what a spec should contain.

> Hi, I have an opportunity to produce a user's manual (about 150 pages) for a
> company that makes software and hardware used in hospitality services/
> restaurants.

> Using engineering specs, the client wants a user's manual done in Microsoft
> Word. Currently I work onsite several days a week for another client and
> would only be
> able to devote so many hours a week to this project, (probably at night and
> weekends). My question involves using engineering specs to write the manual.
> Have any of you done this before without actually using the
> software/hardware?
> And if you have, did you also interface with engineers for your questions ?

I have never written a user manual without first seeing and using the
software/hardware, and I don't see how it could be done effectively.
Test scripts, OTOH, are feasible and must be written in advance in
most cases. But you don't need help with that. I always work very
closely with the engineers. If they are not available to you and
neither is the product, that had better be one heck of an engineering
spec!

I suppose if there is no way you can get hands-on access to the
software/hardware, how well this project goes depends on the following:

1. How complete and accurate the engineering specs are, which is
affected by the standards and practices of the company and/or spec
writer(s).

2. Has the engineering staff adhered to the spec? I hope this does
not surprise you, but many developers deviate from the original spec.
In some circles this is considered "creative license." In some cases,
the changes are necessary to work around some unforseen technical (or
even marketing) problem/glitch.

Though, you may luck out and find one of those companies that creates
detailed and thorough engineering specs, to which they adhere with
religious fidelity, and amend sparingly with modifications should they
ever be forced to wander.

If they are anything like my current employer this spec will simply be
a vague wish list or sketchy plan that also happens to be poorly
written. In the meantime, they expect the writers to work from this
document to produce a manual that accurately represents the final
product, which we get to see very late in the process, and which
bears little resemblance to the spec (anemic as it was). I frequently
have to start by writing *fiction* (making "logical guesses") and
gradually correct the information as I glean the truth. The gleaning
process is painful and fraught with difficulty, because I must badger
and dog (no furry fandom implied here) the engineering and QA staff
for information. I've even accepted source code and engineer's
journal notes, or sneaked through engineering files for clues.

> My concern is that I can do this project *without* having to be onsite. I
> haven't actually seen the client yet or the specs/manual, etc. So this is
> quite preliminary, but I'd
> appreciate any advice you may have about things I should be anticipating
> using
> engineering specs to write the manual. Thanks, Suzanne

Obviously, if you cannot work on-site you cannot implement some of the
strategies that I listed above. Before you promise too much, though,
you may want to read through those engineering specs. If they seem
sufficient to aid you in this task, then you're in pretty good shape.
In addition to previewing the specs, I would ask to have a moment to
walk-through the software. This will help you see just how well the
specs represent the actual product. Also ask if this product is still
in the development process. I hope this helps. I wish you the best.

Diane J. Peters
Technical Writer at AXENT Technologies (a division of Raxco, Inc.)
2155 N. Freedom Blvd., Provo, UT ph. 801.227.3775
diapet -at- axent -dot- com (cc:Mail) or dj -at- ibapah -dot- raxco -dot- com (Unix mail)

The road to enlightenment is long and difficult...
So, bring snacks and a magazine.

BTW: My views are mine and mine alone.


Previous by Author: the Queen's English (was Re: "Proper use of commas in England?")
Next by Author: Talking Birds (was Re: the Queen's English)
Previous by Thread: Re: Advice on User's Manual
Next by Thread: the Queen's English (was Re: "Proper use of commas in England?")


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


Sponsored Ads