Documentation phase in software-development life cycle?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Vlad Dracul work for <<...a software start-up in which technical writers are
expected to write in tandem with the development process, i.e., the
software-development life cycle has no definite phase for documentation.
Often, technical writers in this company have to write about features even
before they are fully developed and stabilized.>>

This is fairly typical. You'll almost never see a situation where the
release schedule is so relaxed that you can wait for a finished product
before beginning your documentation. A good survival strategy in such
situations has two aspects: First, recognize that you can only create "this
is what it's supposed to look and work like" documentation in your first
draft. Plan to set that aside for some time before you do the traditional
second pass to revise and polish the documentation before submitting it for
review. In the time elapsed before that second pass, many changes may have
occurred, so this is your chance to compare the docs against the current
state of the product.

Second, build good enough relationships with the developers that they'll
keep you apprised of what changes are happening. This lets you revise the
docs as soon as the changes are reported to you. If you're really lucky,
you'll be able to persuade the development staff to mostly stabilize the
interface early on and spend the rest of their time concentrating on tuning
the underlying code; this is a great productivity enhancer for them too,
since they spend their intellectual resources where they're most necessary:
on the code.

Developing some expertise in interface design (read Alan Cooper's and Jeff
Raskin's work on this subject) lets you work with the developers to come up
with more effective interface designs that won't need continuous, ongoing
tinkering. (I'm fortunate to have acquired enough expertise to earn the
respect of my developers, to the point that now they often bring me into the
design phase at the start so they can produce a usable interface in only a
couple passes rather than tinkering endlessly with it. They even ask me for
advice on what would work, or how to fix things they're having trouble with.
<insert loud cat purring noise here>)

Where that's not possible, you may at least be able to recognize which
developers tend to stabilize the interface while continuing to tinker with
the underlying code and which ones are incessant tinkerers. Knowing this
will reveal which components of the product stabilize first and can be
documented right away, with minimal rework, versus products in such a
tremendous state of flux that there's no point even starting the
documentation yet.

<<Those administering the development process have been requested to
incorporate a documentation phase into the release cycle so that technical
writers can work with a stable, tested product. Unfortunately, this request
has been turned down, and the reason provided for this refusal is that the
company follows a three-month release cycle and hence has inadequate time
for a dedicated documentation phase.>>

That's actually a reasonable response; unless you can change the release
cycle (which may be impossible for very good reasons), you have to meet
those release dates. The better solution is as I've mentioned above:
stabilize the interface first so you can work in parallel with the
developers rather than having to wait for them to finish.

You can sometimes sell this concept to the development managers by pointing
out that it's traditional in just about any branch of design, from
architecture to engineering, to establish a really good blueprint first that
will be largely unchanged, then let the professionals work on the details of
that blueprint. Ask them whether they'd build a house by constantly changing
the blueprints as the house was being built. When they concede that this is
a bad idea, ask them why software is different? There are no materials costs
per se, but the cost of ongoing chaotic changes is equally high, and the
consequences of unmanaged change are equally severe.

Much of the time wasted in software development could be saved simply by
"measuring twice, cutting once"--that is to say, by coming up with a "good
enough" design right from the start, and not changing it unless you discover
problems during the coding phase. Getting involved in stabilizing the
interface design early is an excellent way to start reaping the benefits of
this approach. Indeed, there are a few companies worldwide who don't even
start coding a product until they have a very good, very functional, very
_tested_ interface. Wish more people understood this approach!

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
(try ghart -at- videotron -dot- ca if you get no response)
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 

"Wisdom is one of the few things that look bigger the further away it
is."--Terry Pratchett

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
?Mustang? (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.