Avoiding documentation bottlenecks while maintaining quality?

[Geoff Hart]

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  
efficiently?>>

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.ca / geoffhart at mac.com
www.geoff-hart.com
--------------------------------------------------
***Now available***  _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)