Avoiding documentation bottlenecks while maintaining quality?

Subject: Avoiding documentation bottlenecks while maintaining quality?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com>, SB <sylvia -dot- braunstein -at- gmail -dot- com>
Date: Sat, 22 Sep 2007 09:48:27 -0400

Sylvia Braunstein wondered: <<Our company is growing extremely fast.
Most of the time, we have to write the documentation pretty much
while the product is being developed and undergoes quality assurance.
The documentation is one of the requirements for product delivery and
many products are being developed simultaneously. Documentation is
often becoming a bottleneck.>>

That's fairly typical, and it leads to a common problem: you can't
document the final product until it's nearly ready to ship, and by
then, it's too late because nobody is willing to wait another few
weeks for you to produce the documentation.

<<What is the best way to meet the deadlines (management-wise)
without sacrificing quality or contents and without being a slave
driver? How do I avoid bottlenecks and get the work done well and

In an ideal world, people decide what the product will do and what it
will look like before they begin work, and stick to those
specifications. Because the design is essentially finalized before
anyone begins building the product, you can start documenting the
product right from the start. At the end, all you need to do is
account for the inevitable few design changes that result from
unexpected problems encountered by the product developers that
required design mods to solve. But 90%+ of the design will still be
exactly as it was specified, so you'll have relatively little
rewriting to do, and that will come during the final QA stage, when
you compare the docs against the shipping product.

Many hi-tech companies resist this concept fanatically. They seem to
believe that cars are built on assembly lines as the result of dozens
of assembly-line workers who change shapes and features and
components according to whatever takes their fancy, and that houses
are built "instinctively", without any reference to blueprints or
coordination between the builders and with each builder doing
whatever strikes them as most interesting at any given moment. Based
on that belief, they assume that software and computers and etc. can
be built without no firm design and with continuous design revisions
throughout the process. Clearly, none of these fanatics is aware of
how mature industries produce things and none has actually seen
anything real being built.

In these environments, all you can do is surf the wave and hope it
breaks before you do. There are survival strategies you can use to
master the wave, but they're not comfortable strategies and sometimes
the wave still drives you under. One good strategy is to create
standard templates that facilitate the writing work, thereby saving
writers from having to reinvent the wheel each time. See my article
on dynamic style guides (http://www.geoff-hart.com/resources/2000/
dynamicstyle.htm) for guidance.

Single-sourcing principles (i.e., finding a way to reuse content)
also helps: get it perfect the first time, then reuse it dozens of
other times. You may not have time or a true need for a fullblown
single-sourcing strategy, but keeping that principle (reuse) in mind
will reveal some efficiencies.

Another strategy is befriending the product developers or at least
becoming a valued colleague so that you can remain aware of changes.
If they consider you important and worth working with, they'll keep
you in the loop. If they don't, no amount of bureaucratic finagling
will get them to cooperate willingly, and you'll constantly be trying
to figure out what changed. Figuring out how to work well with these
people is your only way to know what changes are coming. If you see
the change, you can document it; if not, you can only spot it (if
you're lucky) at the end of the process during QA, when it's too late
to do anything other than spackle over major structural problems.

Last but not least, think "triage": You can't do everything on time,
and can't do it equally well for all things. So ensure that the
crucial information is perfect, the important information is pretty
darn good, and the details are ignored if you run out of time while
getting the first two categories completed. Aim for "good enough",
not "perfect"; you'll rarely have time for the perfection we
perfectionists crave. Then make careful notes about what problems you
lacked time to solve so that you can solve them (make the important
information perfect and the details pretty darn good) in the downtime
between product releases. There's always downtime, even if it's never
as long as we might like.

In terms of reviews, there are half a dozen (maybe more) relevant
articles on my site (http://www.geoff-hart.com/resources/
bibliography.html) that discuss how to make the review process
effective. Pondering them will help you make the reviews work better
for you.

<<I guess we probably need more Technical Writers.>>

Sometimes you really do. Keep good statistics on how long it takes to
accomplish certain key tasks in your workflow, and use that data to
make your case for more workers. Time and workers are budget items
just like money and parts inventories, and if you can't quantify your
needs, you can't persuade the bean counters to fund them.

-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
***Now available*** _Effective onscreen editing_


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Avoiding documentation bottlenecks while maintaining quality: From: SB

Previous by Author: Persona-based design, documentation and testing?
Next by Author: Biz: Be careful how you screen your e-mail!
Previous by Thread: RE: Avoiding documentation bottlenecks while maintaining quality
Next by Thread: Re: Avoiding documentation bottlenecks while maintaining quality

What this post helpful? Share it with friends and colleagues:

Sponsored Ads