Documentation change cycle?

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

Esther Asham reports: <<A gentleman from our sales departments decided that
he wanted to adopt different terms and hence needed the documentation
(on-line and manual) to change. Product Management agreed to that, except
that I said
I can not change my documentation until the Product Management Requirements
Docs are updated. (I am working in a start-up and hence we no policies nor
procedures)>>

Although it's important to keep the requirements doc up to date (if for no
other reason than to protect yourself), don't get hung up on "process":
processes should help you produce quality, not prevent you from responding
to necessary changes. Are the requested changes important, or is Product
Management just caving in without really considering the issue? If the
changes are irrelevant or perhaps even wrong, fight them, and establish a
precedent that changes must be reasonable, not arbitrary. If the changes are
good ones, and will help users, then incorporate them in the docs and don't
worry about the requirements doc just yet. You should, of course, eventually
update the requirements doc, but if the changes are important enough to
make, then they're important enough that someone _must_ spare an hour of
their time to update the requirements.

Use this problem as an opportunity to make everyone understand why late
changes are a problem, and to get the Sales department involved much earlier
in the process. If everyone gets a say on the requirements doc before you
actually begin working, there should be far fewer changes late in the
process for future projects. (Of course, you have to have management who are
good enough to ensure that the requirements doc is well designed, and that
each group lives up to their responsibility to do good, formal reviews at
the beginning. If not, adhering to any process won't happen.) That's not to
say that someone won't suddenly, right before you print the manuals,
discover something that _really must be changed_; thank them, make the
changes, and be grateful that you caught the problem before your audience
did. The best process in the world will reduce how often this happens, but
will never eliminate it entirely, and no process should prevent such changes
from being made.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer