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:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Thu, 3 Jun 1999 14:15:04 -0600
Lief Erickson 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.
Sorry to respond to this thread so late! (I let a lot of
messages accumulate in the techwr-l folder last month...)
My answer is that it all depends on where you draw the line
between requirements and design. Different people draw that line
differently, and thus you get different answers. Here's where I
draw that line. I think of requirements as being mainly about
the problem domain of the software: what's in the problem domain
(goods in a warehouse? machinery? accounts? conference rooms
to schedule?) and what effects the software is intended to
produce there (giving people information about the present
contents of the warehouse, controlling the machinery, tracking
debts in accounts, ensuring that no two parties think they have
the conference room at the same time).
The interface designs of the software are rules of behavior that
implement the requirements. An interface design typically
involves both rules for how the computer's input/output devices
are to supposed to behave as well as how the users are supposed
to behave. The idea is that if both computer and users behave
as intended, then the requirement statements will become true.
(The program code is what makes the computer do its part in the
interface design.)
Now, in very few projects is the user's role documented or even
thought about very carefully. But it's usually critical for
meeting the requirements. If the software is supposed to help
settle accounts between two telephone companies, and it's
designed on the premise that certain users will type in
information about construction and negotiation activity performed
by those telephone companies, then those users had better know
what they're supposed to do or the accounts won't get settled
properly.
That, as I see it, is where the user's manual comes in, at least
in typical business software. The user's manual tells the users
what they are supposed to do in order to fulfill the
requirements. If one of the requirements is that users can get
information on demand about the maintenance histories of cars at
a car-rental shop, then the user's manual has to tell them what
actions to take to run a query on the maintenance histories of
those cars. If other users need to type in maintenance activity
as it occurs, then the manual needs to tell them when and how to
type this information in.
The user's manual thus tells users what to do in order to bridge
the causal gap between the software's screens and the software's
problem domain. It very often needs to inform users about the
problem domain--for example, it might need to explain to users
how to read the scribblings made by doctors on patient histories,
how to tell when needed information is missing from a form, and
who to ask to provide that information. That kind of
problem-domain information belongs in a requirements document.
But the screens and procedures for operating the software are
invented by the UI designer as ways to achieve the requirements.
So you simply have to wait until at least some of those screens
and procedures are designed before you can write the user's
manual. (In some companies, these screens aren't designed until
90% of the program is written, and the procedures are never
designed at all. So the tech writer has to design these
procedures himself, somewhat ad hoc during the last week or so
before the software is released. Oh well...) With a really,
really good requirements document, you can do a little sketching
and planning of the user's manual before the UI is done. With an
everyday "high-level" requirements document, you can't even do
that.
Notice that what I'm saying is very different than, "Well, the
requirements or UI change during development, so you can't write
the manual before, during, or even after development." Of course
specs change. Specs don't just change in software development,
they change in lots of fields. If the specs change, then change
the manual. In principle, you don't need to wait until the code
is written before you write the manual. In practice, when the
code is written, people refine the UI design and sometimes even
the requirements, necessitating changes to the manual. If the UI
design is completely in flux, then yes, you might want to wait
until the software is working before writing the manual. Alas,
we often have to do it that way.
Prototyping is one way to try to get a reasonably stable UI
design and requirements earlier in the development process, so
people can make test plans and user's manual concurrently with
the heavy coding. Incremental development is also something to
look into if you're doing a project of any size. In incremental
development, you release working versions of the program that
implement only a subset of the functionality. That enables the
testers and documenters to test and document the previous release
while the programmers work on the next one.
Notice, though, that these are all tricks for giving you
something stable to document without having to wait for 100% of
the program code to be complete. They don't change the
underlying principle that in order to write a user's manual, you
need *both* requirements/problem domain information *and* a
user-interface design, including both screens and operating
procedures (at least for typical business software).
