Any ideas for a presentation on the documentation process? PART 2 LONG

[John Posada <jposada01 -at- yahoo -dot- com>]

Yesterday, on the way out of the office, I posted a
reply about ideas for a presentation....the peanut
butter thing.

I thought I'd expand on that based on some responses
that I received and some further thought I've given
it.

The reason I selected that topic is when you propose
the idea to a group of people that have never written
procedural documentation is that the first thought
through their head is "Shoot...that's easy...I've been
doing it all my life." in a similar manner to them
thinking in real life, "everyone knows how to bring up
a server, it's just a normal part of being a system
administrator."

It's only when they start to write about making the
sandwich, that they realize that they forgot to
describe how to remove that little plastic strip from
the jar, the inner safety lid to the peanut butter jar
that is glued to the rim of the jar, which end of the
knife to grab without cutting themselves, how big of a
"glob" do they grab, or that they need to apply the
jelly to the same side of the bread as the peanut
butter.

However, it's not just one sided...you cannot expect
them to equate those ommissions with the ommission
that are made in real life...things like "make sure
you are grounded before touching that [$25,000]
computer chip." and how DO you ground yourself? "Ah,
NOW I know what that thing that looks like a hospital
bracelet and metal string is for!"

Some of the other responses I got back made the
sandwich process more complex. The process is complex
enough...why make it more so. 

The more stipulations you add to the process, the more
opportunity you have for the developer to say "Yeah,
but any process can be difficult if you add enough
stipulations...my process is straight-forward."
Instead, after you've demonstrated how difficult it is
to do something "easy", then discuss how much more
difficult it would be if after the peanut butter but
before the jelly, you changed the bread from white
bread to whole wheat, or once the jelly is on...what
would be the issues to toast the bread in a manner
similar to upgrading the operating system after you've
described the process for installation? 

As the instructor, do this by taking one of the
instructions and for every ommitted step, choose the
wrong way to do it.

Make it fun, but remember you are there to describe
the  documentation process...but don't forget to
equate the tasks to the similar tasks that are part of
the real job.

Then ask them to write the same instructions for
peeling an apple. (Did do you remember to describe how
to hold the apple?)

Another fun one is to tie a shoe lace, but not have a
shoelace available to use during the process in a
manner similar to having to write instructions for a
Ver1.0 software install that will be different from
the Ver0.5 alpha version that you are given.  Can you
imaging trying to tie a lace by just visualizing the
process?

At a previous contract, my counterpart in the
development group; the one I had to go through to get
my information, showed with VERY obvious contempt for
the concept of having to create documentation. In his
eyes, I was scum, not worthy of being on the same
network as he was...I was a waste of an IP address.

Then one day, I walked up to him and told him "Ya
know, Rich..my job here is to document how to peel an
apple, not more or less.", then walked away.

Several hours later, he came to me and asked me what
the hell I meant by that? We started talking about how
my job was to document all the little details that
others forget, that causes his beeper to go off at 3am
because on the third shift where the "rejects" worked,
might not know a process to shut off the alarm after
the network was fixed, even though they knew how to
fix the problem itself. 

Suddenly, I wasn't a liability to him, I might actualy
make his life easier.  From that day on, whenever
someone would ask him what my job was, he would wink
and say that I was there to instruct his programmers
on how to make a fruit salad.

Ya do what ya gotta do.

=====
John Posada, Merck Research Laboratories
Sr Technical Writer, WinHelp and html
(work) john_posada -at- merck -dot- com - 732-594-0873
(pers) jposada01 -at- yahoo -dot- com - 732-291-7811
"The art of creating software that is usable by individuals is a communication skill. It is not a programming skill."
                    --Bill Atkinson, creator of MacPaint and HyperCard
__________________________________________________
Do You Yahoo!?
Bid and sell for free at http://auctions.yahoo.com