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.
Subject:Re: Dev. Cycle and the Manual From:"Jessica N. Lange" <jlange -at- OEE -dot- COM> Date:Wed, 5 May 1999 07:56:59 -0400
<<Is it possible to have a user's manual near completion at the end of the
requirements phase of development?>>
Several years ago, my employer decided to enter a new market. They invested
time to research what currently existed and what was wanted/needed. The lead
developer wrote a sw Requirements document and a Functional Specifications
document, both quite complete. When the sw team was assembled and began
coding, I began writing the manual based on the FuncSpec.
By the time I saw the first (buggy) build of the sw, the manual was
complete: at least as to topics and structure. There were a lot of questions
(written right into the book) that couldn't be answered until I could use
the product. When I did get to use it, I already knew a lot about the
product, so my questions and responses to what I saw/used were fairly
knowledgeable. The feedback to the developers influenced changes in the
product.
When the product was ready to ship, so was a very complete manual. The
manual I wrote was a *reference* manual, not a task-oriented manual. It
started with the first command on the first menu and went all the way
through to the end. (We do not sell our products without training, usually
two+ weeks at customer site, so reference manuals are appropriate.)
I don't know how feasible it is to write a task-oriented manual based on the
SW developer's documents, but a reference manual of this type was pretty
easy to do. The second version of this manual was restructured completely
to group information according to the workflow, but some of that structure
was only evident after the sw was completely done.
May I say that I have also written manuals for mature sw products that had
no documentation at all as to what something is supposed to do, why it does
it, how A interacts with B, etc. [Sometimes happens when one company VAR's
another's product, and the other company is 2 guys in an attic overseas
somewhere.]
That task was simply detective work--very satisfying in its own way
("Eureka! So *that's* how it works!"), but also *very* time-consuming. And
occasionally the deductions were incomplete or only partially correct. I did
have help from trainers and a sw engineer who was supposed to support the
product in the field. Those sessions of guessing and discovering were
frustrating and fun.
So, in my experience, working from the FuncSpec (and to some degree, the
Requirements doc) produced a better manual more quickly. But the manual
wasn't complete until the software was.
(VAR = value added retailer)
----------------------------------------------------
Jessica N. Lange mailto:jlange -at- oee -dot- com
Technical Communicator, Ohio Electronic Engravers, Inc.
