Content moratorium: what to do when the interface keeps evolving?

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

Colin Green reports the familiar problem of products remaining in flux right
up to the release date: <<I need to establish a
content moratorium for my final document release. Right now, I'm being asked
to release "final" drafts of user guides while the product is still in flux
- sometimes a full month before the release date.>>

This is an unfortunate fact of life in many software development processes.
It's not a particularly intelligent way of doing things, since it means the
developers do everything multiple times instead of doing it nearly right the
first time, but it does work--sort of. In the long term, you can make your
life a lot easier by working with the developers and their managers to come
up with a considerably more mature process in which the developers work to a
relatively firm design spec; it's not too hard to convince a manager who
must also meet deadlines that they'll meet deadlines better, with better
results, if they figure out how to reduce the number of times each job gets
done. In the meantime, you need to find a friendly way to encourage the
developers to keep you up to date on the ongoing changes. (That requires
substantial relationship building, and won't ever be perfect, but it's a
huge step in the right direction.)

<<I end up wasting time re-writing things as the product morphs>>

Work as closely as you can with the developers to get an idea of which
aspects of the interface are mostly stable, and concentrate your efforts
here first. Once this material is documented, move on to the
next-most-stable parts, and so on. The only way to know what to work on is
to be sufficiently friendly with the developers that they tell you what
they're monkeying around with. This intelligence gathering can take a lot of
time, but less time than rewriting everything a dozen times.

<<I end up "fixing" the docs long after their scheduled release date  - and
I 'm harassed for being late on the schedule.>>

Sometimes it's just a matter of sitting down with each developer and asking
them how they expect you to document something that you don't know has
changed. (otoh, I did once have a developer tell me that it was easier for
me to scan the entire interface for changes than it would have been for him
to tell me he was working on the File menu that day so I could pay attention
to only that menu. Sigh.) One thing that works really well is to institute a
formal review policy: no documentation ships until it's been signed off by
the developer. So you do your best to document each feature, then send it to
the developer, and he reviews and returns it to you. If you see no changes,
print that sucker; if there are problems, produce the signed-off
documentation and point out that it was approved. If there are changes,
negotiate a deadline for implementing the changes, then return the updated
document for review. Both the latter points represent good quality control
steps, but they also cover your ass, so be careful that you don't look like
you're doing them purely to make a point.

<<Thus far education has not worked.>>

In most cases, this isn't because the developers are stupid: they already
know that you can't finalize the docs until they finalize the interface, and
repeating that message just gets them to thinking that you believe they're
stupid. Bad way to build a productive relationship. In most cases, the
problem is that they're so frantic to meet their own deadlines that they
don't have time to worry about yours. One possible way to help everyone
would be to get yourself involved in the interface design; if (as I've
occasionally done) you can show the developer a better way to build the
interface, they'll often happily adopt that interface and then freeze it,
leaving you free to begin documenting it and them free to tinker with the
innards and forget about the interface henceforth.

<<I need a dumb-down rule>>

Nope. You need a _realistic_ rule that accomodates everyone's needs--better
yet, you need a flexible means of living together, not a hard rule. If you
start thinking "dumb", it poisons your way of thinking and sets up an
adversarial relationship that will only make things worse.

<<Given the flux of software applications in development, and my inability
to affect that schedule, what is a reasonable demand for a tech writer on
content moratorium?>>

Sue Galagher, a longtime techwhirler, once had a sig along the lines of "the
documentation is final 2 weeks after the interface freeze". Sounds pretty
reasonable, particularly if you've adopted my earlier suggestion of ignoring
the stuff that's in constant flux and concentrating on the parts that are
stable.

<<what can I reasonably demand for number of days/weeks that the product be
stable in order to compose a final
draft?>>

Negotiate this with each developer or manager; you could set a standard
time, but the advantage of negotiation is that it forces you to talk to the
developers and forces them to talk to you and become aware of your workload,
and that's the key to building a relationship. Each new task can only get
added to the bottom of the list, and though Managers may be annoyed by this,
they're rarely stupid enough to believe it's your fault.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15.  http://ieeepcs.org/2001/

---
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.