RE: Help on Coordination between Engineers and Technical Witers

["Bill Trippe" <btrippe -at- nmpub -dot- com>]

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
already,
because the answer is "process."  I have worked for two successful software
companies where we redesigned our process to conform to something like ISO
9001
and the Capability Maturity Model for Software (CMM, see some background at
http://www.sei.cmu.edu/cmm/cmm.html, and note also that CMM is being
sunsetted
in favor of CMMI (Capability Maturity Model Integration)).

A great deal has been written about such processes, but I would like to
offer
some highlights of what I learned from going through the process twice--once
on the customer support side of the business (including training and
documentation)
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
Support,
   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
design
   phase until the functional specifications have been approved (pretty
obvious,
   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
frozen;
   for release to Alpha that the installation scripts and documentation be
complete.
   Again, pretty obvious, but the details are important.)

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

One more quick thought.  If you haven't already, you might consider an
outside
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
consultant
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

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

See http://nmpub.com/blog/ for "Ideas in Technology and Publishing"