Re: Examples

Subject: Re: Examples
From: Keith Hood <klhra -at- yahoo -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 28 Jul 2007 22:58:32 -0700 (PDT)

Ladies and gentlemen:

Sorry if I alarmed you. I think I didn't provide
enough detail in my original post; perhaps it's time
for some explanations. The situation is really not as
dire as you think.

First, the audience for these user docs is miniscule.
This is a very special-purpose system with a user
group of perhaps 15 people at any given time.

Second, it's a fairly small application. There are
only 16 user level operations. The longest of them has
only 14 numbered steps in the instructions.

Third, as I tried to explain to John Posada earlier,
the process of actually laying out and creating the
documents is fairly cut and dried. I have templates
that can be easily adapted to this project. The
functionality in the product has so closely followed
the design documents that the large majority of user
document content can be lifted word for word from the
use cases and the functional requirements. (Contrary
to what I understand is normal practice, the boss
wanted the UCs and FRs to be fanatically detailed.)

Fourth, I have made arrangements with my boss to
conduct surveys and interviews with the users to gain
more information on their habits and concerns and the
ways they actually use the application. And I've made
a couple of questionnaires for that.

I think I'm doing OK. I started working on the user
stuff last Monday. I have
* Created the outlines (incipient TOCs) of all the
* Done extensive text outlines that will become the
indices for all documents (I'm kind of OCD about
* Archived graphic files of all the illustrations
that will be used
* Put together a document that has lots of examples
of different possible layouts for the pages in the
user procedure guide (I'm still kicking around ideas
about how the pages should be organized)
* Made a Freemind diagram that shows all the
cross-reference links that will be used
* Made arrangements to subcontract proofing and
* Checked with the boss to compile a list of all FAA
regulations that apply (he says)
* Taken the Visio flow charts I made earlier about
system operation and begun chopping them down to
remove the parts the user really doesn't need (about a
third of them are finished)
* Finished the glossary

I haven't bothered to make a list that relates the UCs
and FRs to the user level procedures, because I did
that in the spreadsheet I used to track the creation
and versioning of the design docs.

I know things can change, and that's why I'm in
constant contact by email, phone, and IM with the
developers. I get updates of the almost-completed
application, and test run it, almost every day.

I guess I appreciate your being concerned enough to
tell me you think I'm sitting on a toilet with
nitroglycerine in the tank, but please, what I need is
not notice that you think I'm about to die, what I
need is pointers toward examples of things you think
are particularly good user documentation. Maybe my
ideas aren't right and it would help me to see
something better.


Moody friends. Drama queens. Your life? Nope! - their life, your story. Play Sims Stories at Yahoo! Games.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Re: Examples: From: Gene Kim-Eng

Previous by Author: Re: Examples
Next by Author: RE: Examples/one other thing
Previous by Thread: Re: Examples
Next by Thread: Re: Examples

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

Sponsored Ads