Re: Walk-throughs (long but not too long-winded)

[Deborah Ray <debray -at- RAYCOMM -dot- COM>]

At 01:49 PM 6/2/98 EST5EDT, you wrote:
>I was wondering if anyone out there had ever conducted a manual
>walkthrough, either in the preliminary or final stages. I'm looking
>for a different approach to our walkthroughs. I work for a company
>where nobody wants to sit down and dedicate a few hours to the
>quality of our manuals.

Seems that there are two issues going on here: getting support
from management and getting folks to attend/participate in the
review meetings. I ran into a similar situation a few years ago
and, after honing my own procedures a bit, ended up having
some success. I started with already having support from my
manager, so the following scenarios address getting people to
attend and participate.

WHAT DIDN'T WORK
1. Write.
2. Revise.
3. Write.
4. Revise. (Repeat steps 1 through 4 as needed.)
5. Compile the draft.
6. Stand at the copier for hours.
7. Distribute the draft to engineering team with verbal
   review guidelines and verbal announcement of the
   meeting date and time.
8. Arrive at the review meeting.
9. Sit and twiddle thumbs while (a) nobody attends or
   (b) nobody has anything to say, despite specific and
   leading questions from me.
10. Eat doughnuts.

WHAT DID WORK
1. Write.
2. Revise.
3. Write.
4. Revise. (Repeat steps 1 through 4 as needed.)
5. Compile and copy the draft.
6. Draft a memo that includes specific review guidelines
   and announces the meeting date and time.
      * For example, specify that reviewers are to look
        at technical content, diagrams, and overall
        organization, and specify that reviewers are NOT
        to look at yada yada yada.
      * Specify in the memo that the meeting will be their
        opportunity to voice their opinions/corrections/
        additions and that "if you do not present your
        opinions/corrections/additions at this meeting, I'll
        assume that you have none and the document is
        completely accurate and ready to be published as is."
        (Where I worked, each engineer had a
        specific role in developing the equipment, and no
        engineer wanted to be responsible for product failures
        once the equipment was in use.)
      * If you want to be really thorough, create a
        boilerplate example of a few marked up pages,
        illustrating the things you want them to review.
        (For, say, an hour's worth of work on your part,
        you can show people what you want *and* have the
        example to reuse later.) Of course, the level of
        detail here will depend on what stage of the
        writing process you're in.
7. (If possible...and this point it key) Ask your boss
   (or management) to review your memo and *sign off on
   it*. If you can, have your manager co-initial the memo.
   Doing so helps indicate that folks are expected to
   attend and participate. (As I said, I did have support
   from my boss, so this was not a difficult issue.)
8. Distribute the memo.
9. Send a reminder memo/email the day before the meeting,
   requesting that they bring the marked up document to
   the review, and include (again) the review guidelines
   information.
10.Attend the meeting.
      * Start the meeting on page 1 of the manual,
        going paragraph by paragraph.
      * Use the review guidelines document you distributed
        as a launching point for discussions on each page.
      * Have your own questions ready. Doing so can clarify
        points AND help open discussions.
      * Wear a smile...and your invisible armour. (In my
        experience, if the engineers spent time on the
        document and had to attend the meeting, they'd be
        darned sure to make themselves heard....)

Sound like a lot of hubbub to go through? It is, but
the results for me were well worth it. I ended up with
thoroughly-reviewed, technically accurate, well-organized
documents. More importantly, though, it helped establish
a better relationship with the engineers. For example,
because of the review meetings, engineers actually
communicated with each other and found gaps in product
functionality, identified potential safety issues, and
worked through troubleshooting procedures. Also, the
engineers seemed to like the idea that their time/efforts/etc.
would yield results/changes/etc. in the documents. In a
sense, I'd give them some control over the outcome
of a document, which seemed to help get them thinking and
contributing.

HTH, and good luck!
Deborah


**************************************************************
* Deborah S. Ray, debray -at- raycomm -dot- com, http://www.raycomm.com/
* co-author _Mastering HTML 4.0_, _HTML 4 for Dummies Quick
  Reference_, _The AltaVista Search Revolution_, and others.
* RayComm, Inc., currently accepting contract inquiries.