Re: Quality/validation (long)

[Karen Gwynn/Datatel <Karen_Gwynn -at- DATATEL -dot- COM>]

Rick Lippincott wrote ...
This is a response to the anonymous posting concerning QA/validation
problems.

I think that three parts of your problem are

* Busy developers who don't want to review the manuals
* QA's confusion on the actual tasks involved
* Personality problems

Busy developers is a problem that's tough to overcome. Some of these people
just don't -want- to do it. They see their jobs as developers, not reviewers.
(I don't have any direct observations to prove this, but I'm sure when they
were preparing for their careers they didn't sit in the dorm at night and
say "Oh boy, I can't -wait- to review docs....") Really, the only solution is
to move the brunt of the QA/validation away from the developers. Sure, include
them in the loop. Sure, give them copies, and sure, pay attention to what
comments they make. But the developers should be your -second- line of
defense. When they fail to come through, you'll shrug it off. Who needs em?
You've already gotten usable comments from the QA/Validation folks. (I
realize this is a radical idea, but it actually works very, very well.)

<snip>
***********************************************
I agree with his observations (all three points). However, I'd like to expand
on the topic of the the reluctant developer reviewer.

We have experienced the same problem with developers not wanting to review our
documentation. My observation has been that

1. they are too busy. they have 100% of their time allocated to
development/programming and 0% allocated to doc review--or writing (but that's
another issue).

2. they don't know how to review documentation. They don't understand what is
expected of them and when they read what you give them, they think "that's
true," forgetting that there may be *more* to it and therefore not imparting
that knowledge.

3. they just plain don't want to review documentation. When this is the case it
doesn't matter if they have the time and they know what to do: it ain't goin'
happen (this is really a personality/personnel issue and except for bringing it
to the attention of management there isn't much a lowly doc writer can do).

Okay, if there isn't anything you can do about item #3, what about #1 & #2?

Finding the time: Traditionally we (at my company) have given a review copy of
the documentation to each programmer who has worked on the project (or at least
worked on it enough to have some knowledge of the project. Someone who just did
one or two screens isn't considered a reviewer) and then waited--and
prayed--for comments. On the project I'm currently working on there are three
writers and approximately 20 programmers. It doesn't take long to figure that
each programmer could get hit with a lot of doc to review. So, instead of going
to the programmer, I go to their supervisor. Each supervisor is given three
copies of the doc. One copy is for them to review and the other two they are to
distribute to the programmers who (1) have the most knowledge of the subject
area and (2) has the work schedule to complete the review in the allocated time
frame. The *theory* here is that, since the supervisors (we actually call them
area leaders) are the ones who give out the programming assignments, they  know
each programmer's current schedule/availability and can make a better judgment
as to who to give the doc to. Secondly, if the request is coming from the
supervisor, the programmer might view it more as a *real* assignment and not
just something that nudgy-doc-person-wants-me-to-do!

Notice I said *in theory*. Unfortunately I have not been able to try this out
since devising this wonderful idea. However, since the old method doesn't work,
I'm eager to give it a try!

Not knowing how to review: If this is the problem, and the programmer(s) in
question want to do the reviews--then train them! Sit down with them,
one-on-one or in a group, and explain what you expect from them. Teach them
what your documentation is suppose to convey (its amazing how many programmers
really don't understand the purpose of documentation, even the documentation of
their own products). Explain the difference between what they know in their
heads and what you've written on the paper. Explain that, if there are three
options and you've only listed two, it is important that they tell you the
third option! To us this sounds so simplistic and basic that its mind boggling
to think that you have to explain this, but you do. This is not to say that prog
rammers are dumb, its just that they have a completely different point of
reference (I know, making sweeping generalities on this list is a bad thing. I
fully expect to hear back on this one. And I know that there are programmers
who do know how to balance the technical details they live in on a daily basis
with the higher level realities of the end user, but they are not the gems and
not the majority!)

Anyway, that's my $0.04 (too long to be $0.02).

Karen Gwynn
kwg -at- datatel -dot- com