Re: Quality, Documentation, and Mental Blocks

[Steven Jong <SteveFJong -at- AOL -dot- COM>]

That Joe Miller fella sure makes a lot of sense 8^)
(Seriously, Joe contacted me offline, and it's cool.)

Chuck Martin <chuckm -at- EVOLVESOFTWARE -dot- COM> made some
interesting points as well:

>> I defined as an "art" the task of creating the
>> actual software. In response, people replied that
>> programmers who don't follow rigorous procedures,
>> or 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.

Ah, the romantic lone-wolf programmer, whose art cannot be
appreciated by mere mortals, and who cannot be fettered or
slowed by specifications! I've worked with them my whole
life, it seems.

I'm more comfortable in the documentation realm, where I
understand the processes involved, but for that kind of
programming style, the flaws become apparent when you step
back and look at the overall team (of which we are a part).

For example, I remember one guy like that: he refused
to write anything down and simply turned out whatever code
he wanted. Whether it met any user need was debatable.
And when he delivered a build, even one described as
"no user-visible changes, only bug fixes," it took literally
ten of us crawling through the screens to find what he'd
wrought. (And typically two-thirds of the screens HAD
changed.) The funny thing was (and I don't mean funny ha-ha),
his code was extremely inconsistent, screen-to-screen and
build-to-build. When the QA guys would file a bug report,
he would close them with the notation "not a bug--
functions as designed." Hah!

>> That's not to say that some of what they do isn't
>> part of some, higher-level process...
>> [But t]hat 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.

From the outside, it all looks like wizardry, but speak to
an experienced programmer and I think you may get a less
romantic view. Speaking strictly within my own realm, I can
tell you that we can go deeply into the heart of the writing
creation process with techniques and methodologies; for
example, structured documentation and Information Mapping. I
introduced these methodologies where I work, and I've seen
productivity double since then; I don't think it's entirely
a coincidence. And if you get into creating style guides,
you push into the creative process from the other end.

>> 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.

Even to say "better" in quotes is to acknowledge the
ability, and the need, to compare products--software in this
case, documentation in the case we're more interested in.
That's another area where what we do is not art.

To me, quality applies along three axes. The first is
product quality. Given two products of equal quality, the
second axis is process quality. (In other words, good stuff,
cheap.) This is certainly a valid perspective to our
employers, and eminently quantifiable. Your metrics look
reasonable to me.

>> [W]riting software... [i]s done once (hopefully).
>> then,  of course, debugged. Software development and
>> manufacturing are two  entirely different animals.

Yes, writing software (and documentation) is a "once-off"
activity. Engineers and writers create originals; others
make copies.

However, let me go back to the group perspective. I said my
group will turn out about 80 documents this year, yet our
company has fewer than twenty discrete products. We may
document multiple releases in a year; multiple client
versions; multiple documents per product. Each is somebody's
baby, but seen together (and I've seen 'em all), there
are--and must be--many similarities. (The pediatrician may
agree that your baby is the cutest she's ever seen, but
she'll still count the toes.)

>> [H]ere'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."

I think you answer your own question; I would say "yes!"
I would only add that if this is what you say your company does,
ISO would have you document and follow processes that ensure
compliance with all of those statements. How do you KNOW you
are turning out software with only X minor bugs? (By using
testing procedures.) How do you KNOW you are setting a
schedule? (By publishing it.) And so forth...

-- Steve

=========|=========|=========|=========|=========|=========|=====
Steven Jong, Documentation Group Leader ("Typo?  What tpyo?")
Lightbridge, Inc, 67 South Bedford St., Burlington, MA 01803 USA
mailto:jong -at- lightbridge -dot- com -dot- nospam          781.359.4902 [voice]
Home Sweet Homepage: http://members.aol.com/SteveFJong

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