RE: Help on Coordination between Engineers and Technical Witers

Subject: RE: Help on Coordination between Engineers and Technical Witers
From: "Bill Trippe" <btrippe -at- nmpub -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 26 Feb 2004 13:51:43 -0500

Hello Iliana,

Iliana Kostava wrote:

> At my company we're trying to improve the coordination process between
> developers and technical writers. The problem is that sometimes
> technical writers don't get notified of software changes or new features
> that should be present in the user documentation. And vise versa, it may
> happen that developers don't know if something is changed in the
> documentation and they don't check it for correctness. We're seeking for
> a way to define a formal process to solve this issue and place it in our
> quality management system (it's based on ISO 9001).

What a great question, and even better that you answered it yourself
because the answer is "process." I have worked for two successful software
companies where we redesigned our process to conform to something like ISO
and the Capability Maturity Model for Software (CMM, see some background at, and note also that CMM is being
in favor of CMMI (Capability Maturity Model Integration)).

A great deal has been written about such processes, but I would like to
some highlights of what I learned from going through the process twice--once
on the customer support side of the business (including training and
and once on the software development side of the business.

The highlights for me were:

1. There should be detailed specifications (including functional
and design specifications) that are highly readable and meaningful
to all interested parties (including documentation).
2. Such specifications should be subject to regular and formal reviews
by all interested parties.
3. Such specifications should be under a rigorous and visible change control
process. (We even went so far as to have the Director of Customer
which included training and documentation, be one of the signatures on
an approved change.)
4. The entire product development process should be managed in visible
and meaningful phases, and that transitions from phase to phase should
be an explicit event. Thus, you don't consider the product to be in
phase until the functional specifications have been approved (pretty
yes, but not always honored).
5. Perhaps most importantly, that the transition from one phase to another
be subject to an official declaration that the project has reached
a state of readiness to be at the next stage. And that this state of
readiness be defined by a number of meaningful criteria. (For instance,
for release out of the design phase, you could require that the GUI be
for release to Alpha that the installation scripts and documentation be
Again, pretty obvious, but the details are important.)

There is more of course (and I would be happy to discuss off line), but I
these highlights suggest the gist of it, which is that the software
process be orderly, open, and visible, and (here is the key) that all
parties are fully involved and fully empowered to help manage the process to
their own organization's success in the ultimate release and use of the

One more quick thought. If you haven't already, you might consider an
consultant to help your organization with this process. In one case, we did
it on
our own, and it worked because we had a _very_ senior and excellent
engineering team.
In the other case, we were all pretty junior, and we hired an outside
who did an excellent job of "herding the cats," as they say.

Hope this helps, and as I said, I would be happy to discuss offline.


Bill Trippe
New Millennium Publishing
1 West Foster St.
Melrose, MA 02176
781 662 6672
btrippe -at- nmpub -dot- com

See for "Ideas in Technology and Publishing"

Previous by Author: RE: Impagination software.
Next by Author: Re: Financial Market Trademarks
Previous by Thread: RE: Help on Coordination between Engineers and Technical Witers
Next by Thread: RE: RE: Help on Coordination between Engineers and Technical Witers

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

Sponsored Ads