Re: Documentation and CMM?

["Burch, Denise (CAR)" <Denise -dot- Burch -at- VW -dot- COM>]

Hi, Maaike,

I'm working on creating a development methodology that includes some
elements of CMM and relies heavily on documentation. Each phase of the
development process includes a number of templates that must be completed
and signed-off. In addition, the documents go into change control and can
only be ammended by an official addendum, which is also signed off.

The challenges in this documentation endeavor are similar to those you might
expect in any organization:

*       Documentation, as a typically low priority, is often incomplete as
authored by developers and systems analysts (pseudo-solution is to implement
a fairly strong review process with a tech writer included).
*       Comprehensive templates are difficult to create.
*       Tight deadlines often mean action in multiple phases concurrently --
causing sign-off problems and QA risks.

One of the biggest assets in this environment (moving from totally
unstructured to totally structured) has been the acceptance of the process
and templates as evolutionary. We learned that we don't need a 15 page
systems analysis document for a bug fix, so created criteria to define the
scope of a project and its documentation. We were also able to do some
on-the-job training with developers to get everyone on the same page with
standards and terminology. I also make a point to get regular feedback from
those using my templates -- what's working for them, what's not?
redundancies? etc.?

I think, however, one of our biggest challenges is that the
developers/systems analysts don't see the documentation as an essential part
of the process. No matter how many times I stress the need of the documents
for QA purposes, as well as historical purposes, it just doesn't seem to
sink in. The quality of the documents leaves many unanswered questions and
incorporates many assumptions. If they "get it," they don't see the need to
explain further. Part of the problem is that they are so embedded in the
system and the business -- and often are developing from their own systems
analysis documents (rather than having two separate entities for the two
separate phases). But to new developers (who seem to be coming in droves
these days), the documents prove insufficient for orientation and hand-off.
I've tried the ol' "what if you were hit by a bus" scenerio, but they all
seem to think they are immune to mass transit accidents, I guess. I find the
easiest solution to this is to conduct interviews with the systems analysts
or business analysts and fill in the blanks myself. Pieces like the
"glossary of terms" often get overlooked. I'm the perfect "ignorant"
resource for questioning these things though.

Anyhow, in terms of packaging, I'm going to write a methodology user guide
and present it on their intranet with links to resources and downloadable
templates. The important thing to remember is that the methodology must be
somewhat flexible -- not to the point of jeopardizing quality -- but because
it needs to be able to fit in your company's environment. CMM is a pretty
comprehensive and complex approach -- make sure it's not more complex you
need. I'm sure NASA tailored it to their processes -- you should, too.

Hope this was helpful. Please feel free to contact me if you have more
questions.

Denise Burch
burchd -at- concentric -dot- net
Tech Comm Consultant

> ----------
> From:         Maaike Groenewege[SMTP:mgr -at- MEDIASYS -dot- NL]
> Sent:         Friday, February 19, 1999 2:46 AM
> Subject:      Documentation and CMM?
>
> Hi all,
>
> Judging from your posts to this list, I should consider myself one of the
> more lucky techwriters around: I have a real office with real windows,
> doors
> and a real fellow tech writer, two computers (one for writing my docs, and
> one to access the software application I'm documenting), I am invited to
> take part in relevant meetings, and, overall, documentation is taken very
> seriously. (In case of job openings, I'll make sure to post them to you
> first! *s*)
>
> Recently, my company has started implementing the Capability Maturity
> Model
> in its organisation. This basically means that no action that is taken
> should go unaccounted, unplanned or unexplained. The ultimate goal of the
> model is to reach a professional organisation which uses mature
> processes.
> The web abounds with information about CMM, so I won't say too much about
> its details here.
>
> My manager has suggested that documentation somehow should be fit into
> this
> model too, so that the well known "It's three weeks before the final
> release
> date, and oh yeah, we should have some documentation" issue can be
> avoided.
> Although many people within the company have already advised me on how to
> do
> this, I'd like to hear your opinions too.
>
> Does anybody here have any experience with setting up formal documentation
> procedures? Do you have any suggestions on where to start? What
> difficulties
> have you encountered? What benefits did it bring? Did you have trouble
> convincing other people in your company about the benefits?
>
> Thanks,
>
> Maaike Groenewege
> Tech Writer
> Mediasystemen b.v., a Triple P company
> Bloemendaal
> The Netherlands
>
> mgr -at- mediasys -dot- nl
> http://www.mediasys.nl
>
>


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=