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:Jean Richardson <jean -at- BJRCOM -dot- COM> Date:Tue, 4 May 1999 12:17:43 -0700
As an independent contractor, I've worked in a variety of companies with a
variety of approaches to the development life cycle. Some have been
explicit in setting a requirement that the user manual *be* the spec. This
means that it can, indeed, be a deliverable that results from the
requirements phase. It also means that the technical communicator needs to
be involved in the requirements phase and needs to be as conscientious in
researching requirements as s/he would be in researching the UI,
functionality, and usage of a completed application.
I believe your question goes to whether delivering user doc at this phase is
possible. My position is that, certainly, it is possible. My response goes
to whether it is advisable, and under what conditions.
Since I feel personally responsible for the user's experience where the
documentation is concerned, I tend to inquire into the thoroughness of the
planned requirements gathering process. Typically, this phase is poorly
planned and even more poorly executed. Here, then, is the rub. Given a
poorly executed requirements gathering phase, the software delivered to the
user is likely to diverge from the requirements wherever it was discovered
during the development process that the requirements were incomplete,
unclear, or technically impossible to meet within the agreed budget and
Certainly, I would agree to deliver a user information set at the completion
of the requirements gathering process if:
-- that process is robust
-- I am allowed to participate as a full team member
-- the software will be tested *against the user doc* -- rather than any
engineering specification -- by the QA team
-- the software is required to be in full compliance with the user
information before shipping
Achieving the necessary set of agreements to make this possible may be a
challenge. However, I do think that, if you really enjoy software
development and are committed to your users, this will be a more satisfying
experience than a more traditional approach to developing user information.
-- Jean Richardson
At 11:19 AM 5/4/99 -0500, you wrote:
>Is it possible to have a user's manual near completion at the end of the
>requirements phase of development?
>My boss has done some research and found that it is possible, but it goes
>against his understanding of software development. He cannot believe that
>it is possible to have a user's manual complete before the code is even
>written. In our organization we have five software development phases:
>analysis, requirements, design, coding, and testing.
>Please respond regarding the feasibility of having a user's manual near
>completion at the end of the requirements phase. If it is not feasible to
>have the user's manual near completion at the end of the requirements
>phase, comment on where in the development cycle it can be complete. I have
>my opinion, but would like to hear what the list has to say.
>lerickson -at- mqsoftware -dot- com
>From ??? -at- ??? Sun Jan 00 00:00:00 0000==
BJR Communications, Inc.
Portland, Oregon, USA
voice: (503) 788-8998
A provider of:
* Customer contact skills training
* Audience analysis and research
* User assistance life cycle development
* Technical communication products