Re: Quality, Documentation, and Mental Blocks

["Martin, Chuck" <chuckm -at- EVOLVESOFTWARE -dot- COM>]

On Tuesday, December 02, 1997 1:34 PM, Steven Jong
[SMTP:SteveFJong -at- AOL -dot- COM] wrote:
>
> Arlen Walker <Arlen -dot- P -dot- Walker -at- JCI -dot- Com> shared terrific observations
> about ISO 9000 and quality. I defer to his experience, but I have
dealt with
> quality documentation issues in general and ISO 9000 certification in
> particular,
> and I observe that writers wrestling with the concept of
"documentation
> quality"
> tend to hit a series of mental blocks. (You can see it in this
discussion.)
> Sometimes writers are never able to overcome these blocks.
>
> BLOCK #1: Creative art cannot be qualified; technical writing is a
creative
> art;
> therefore, technical writing cannot be qualified.
>
> If you can't get past this, you can't even begin the quality journey.
> Amateur programmers hide behind this same block and refuse to write
specs.
> I liken the documentation process more to a manufacturing process,
> where similarities are more relevant than differences.
>
> This is a hard perspective to take as an individual working on one
document,
> but immediately apparent if you look at an aggregate group.
> This year, for example, our writing group will produce about 80
documents.
> They are NOT all individual, unique, creative works! They are more
similar
> than different.
I think this is an interesting twist, especially as I'm the one who
ventured in the "art" twist. But I don't think I ever said writing
documentation is an art. Rather, many aspects of creating good
documentation are rather repetitive. Not assembly-line repetitive, mind
you, but simply repeating the same sort of steps to insure tasks are
completely and clearly documented.

However, some aspects clearly fall into the creative realm, where
process simply can't cover. For example, you can say that a book shall
have an index. You can even quantify the index (My 64-page,
graphics-intensive manual entry last years in the local STC competition
was faulted because it did not have one page of index entries for every
10 pages of text. This quantification didn't touch on the quality or
completeness of what existed.). You can specify that a Help system will
have browse sequences, but you can't define how to create the most
useful browse sequences for the material.

But, more importantly, I defined as an "art" the task of creating the
actual software. In response, people replied that programmers who don't
follow rigorous procedures, ort who don't create and follow
specifications, as "amateur." I think that's an insult to the true
geekoids who work with pride outside the lines--and still produce
high-quality material. That's not to say that some of what they do isn't
part of some, higher-level process. For example, I'm a huge advocate of
peer code review (but how often does that really happen?). But how can
you quantify with process when you tell your top programmer "We're
adding feature X and feature Y to our ABC product" and that person first
tells you about how long it will take, then goes and finds a way--some
way--to do it? That period of time, from the definition of problem
through the first passes of ideas to solve it, are the heart of the
software creation process.

The most interesting part of all this is if you give the same problem to
different programmers, they'll likely invent different solutions. None
will be wrong. Some may be "better" than others, better in terms of more
efficient code, faster running times, or simply less time to come up
with the solution. But how will ISO9000 quantify this crux of software
development?

>
> BLOCK #2: Consistency is not quality; consistently produced junk is
> still junk.
>
> Consistency is the foundation of quality; Deming said that quality IS
> consistency; ISO attempts to enforce consistency. I think there's a
> mini-block within this block that says "quality means HIGH quality."
> Not so; quality means consistent quality.
>
> Let's say you're the purchasing agent for a large company, looking to
buy
> 1,000,000 widgets. You invite three vendors to submit prototypes,
> and pick the one that works best. Once you approve delivery of the
> remaining widgets, you suddenly care deeply about the vendor's
> ability to deliver consistent quality. ISO 9000 specifically applies
here.
I'll go back to writing software here. It's done once (hopefully). then,
of course, debugged. Software development and manufacturing are two
entirely different animals.

So here's a question then: could you have an ISO9000 document for
software development that says something along the line of "We will
produce the ABC software, releasing it with no more than X minor bugs
and 0 data loss or crasher bugs. We will set a schedule and revise it as
necessary. We will test, document, package, and market the software. We
will hire the best staff we can find to meet these goals."

--
"You don't look American."
"Everyone looks American, because Americans are from everywhere."

- Doonesbury
Chuck Martin, Technical Writer
Evolve Software                  | Personal
chuckm -at- evolvesoftware -dot- com        | writer -at- grin -dot- net
www.evolvesoftware.com           | www.grin.net/~writer


	http://www.documentation.com/, or http://www.dejanews.com/