TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Knowing you're one of the WhiRL-er gurus, but that others aren't, I'll
address this in (hopefully) more detail than I might otherwise (I'm sure
you have the business skills to say "I'm doing a lifecycle doc" and sell
that, but others might not have that experience yet 8-)
>I recently took on a mammoth project. I'm writing a user guide for a
>3-year old in-house program for which NO documentation (except some
>pretty minimal online help) has ever existed. No formal training has
>existed either. The program is really massive...
I've run into this a couple-three-four times... it sounds like you've
lucked-out and gotten a project where you have access to the end-users...
this makes it easier to go whole-hog on the lifecycle doc.
As you've probably noticed with apps that have migrated from the original
UN*X, there is an almost infinite number of ways to work with 'em, and it's
up to the documentation (or internal hip-pocket training from powerusers)
to guide the users through the tasks they need to accomplish.
> [snip] ..... the requirement to document every
>single "screen" (the inhouse term for "window" and/or "dialog box" --
>the terminology also stays). Okay.... so save your breath on that. I'm
>totally frustrated with the requirements, too.
Assuming the powers-that-be understand deep down in their bones the fact
that you're going to have to do a fair amount of work on this, and allow
you access to whatever "powerusers" there are for the product, your idea of
a step-by-step lifecycle document is a good one.... IF you can get
management to buy into that...
>The users range from the GED graduate hired away from the WalMart
>warehouse to marketers to accountants to the telephone receptionist
>to the whiz kids in development. No commonality here....even in
>employers, as about 70% of the workforce consists of contractors.
Having access to users helps you to keep selling really-useful-docs to
management....
Work with the powerusers outside development to develop an understanding of
the lifecycle, aim the process-details at the receptionist and warehouse
gang... you can include an appendix (consisting of just the 753
screenshots with circles and arrows and a paragraph on the back of each one
'splainin what each one does) aimed at the whiz kids in development.
Work thru the lifecycle *first* so you might have something useful.
I used to try to get all the screen shots first and then work thru the
lifecycle, but Occasionally didn't get to go any farther than making
screenshots and talking to developers (just to get the app started) but
that doesn't get the end-users involved... one of the things I've found
most important in such a project is keeping the non-powerusers involved so
that momentum for the thorough documentation remains apparent to the
powers-that-be: evangelise the non-powerusers during testing and
preliminary training as ya get each module drafted.
>Thanks for any advice. And I truly apologize for the length.
What's to apologize for? I think this sort of discussion is much more
useful than parsing macros ;-)
On Mon, 19 Apr 1999, Jane Bergen <jbergen1 -at- EARTHLINK -dot- NET> wrote:
>
>My thoughts have been to trace the life cycle of a piece of equipment
>from purchase to its retirement, and organize the document accordingly
>with a separate chapter for the finance-related tasks that are not
>necessarily tied to a piece of equipment. It will have an index, of
>course. Does that organization sound reasonable or is there a better
>way?
-------------------------------------------------------------
Dan Brinegar Information Developer/Research Droid
"Leveraging Institutional Memory through Contextual
Digital Asymptotic Approximations of Application Processes
suited to utilization by Information-Constrained,
Self-Actualizing Non-Technologists."
vr2link "at" vr2link.com CCDB Vr2Link http://www.vr2link.com Performance S u p p o r t Svcs.
