Documentation/Training

[Tim Pera <uusr656!tim -at- RAMBONE -dot- PSI -dot- NET>]

Chuck Banks, Bonni Graham, Sally Marquigny all raise
good points about the difficult marrige of documentation
and training materials. But to learn why it might be a
good idea to convene documentation and training
materials under one roof, I recently attended a Ziff-
Davis seminar entitled "One-stop Documentation" given
by a man named Conrad Gottfredson who is credentialed in
learning theory/instructional design. His ideas make
sense to me, which I'd like which is why we have budgeted
time to apply his model to a small project.

Very briefly, his thesis is that software documentation
should be written strictly from a functional (as opposed to
software menu-driven) viewpoint, such that the TOC is
nothing but verbs that specify completely everything the
software user needs to do in order to get the job done. He
proposes this structure for each chapter:

A. INTRODUCTION. This consists of a context paragraph, list
of PWEFORMANCE objectives, list of CONCEPT objectives,
definition of terms, and prerequisites. This section sets
the user up for what follows and focuses attention on the
upcoming goal. This with the Review discussed in E below
frames the discussion.

B. CONCEPTS. This section educates users to underlying
principles, making them better prepared to troubleshoot
problems and spin variations.

C. PROCEDURE OVERVIEW. This section highlights the major
steps in procedures (sans excruciating detail) and (a)
satisfies experienced users who are quite happy to eek out
details on their own and (b) can serve as a procedural quick
reference.

D. DETAILED DIRECTIONS. Blow by blow account for new or
inexperienced users who need the reassurance of detail. It
is worth noting that this material is presented in a side-
by-side format (say) where screen input/output is shown or
synopsis-ed on the left and rationale, tips, notes,
cautions, et al are shown on the right.

E. REVIEW AND PRACTICE. This is where we tell them what we
told them and provide worthwhile practice exercises. My
company make database-driven software, so I'm excited about
the possibility of shipping a practice database loaded with
data that we can point to in these exercises.

Based on my experience teaching math in the classroom, it
seems pretty clear that as a consequence of creating
documentation using this model, I've created training
materials as well. If I've prudently included
developers/trainers/help desk people in the development
process, we have something the trainers can take into the
classroom and teach from, because the
principles/procedures/practice exercises are all there.
Having *trained* from this document, the document's efficacy
is proven and students are more inclined when something goes
wrong to reach for the manual instead of bothering a
coworker or calling our Help Desk. And our company (and our
clients) may spend less money on training - remedial
training, new user training, cross-job training.

Question: Any comments about the suitability of this model
for online documentation purposes?

Thanks to Pam Tatge of TI (this list) for recommending this
seminar.

Tim Pera
tim -at- pbs -dot- com