re: Branching procedures

["Christensen, Kent" <lkchris -at- sandia -dot- gov>]

re:  I'm doc'ing mainframe (ISPF) procedures that can include a number of
runtime options.
 
Some programs are just complex, since they automate complex systems.  Best
to just acknowledge this up front, both to yourself as the tech writer, but
also to the readers of your manual.  Having done that, I'd next try to
provide a "big picture" of sorts.  This feels like a good place for an
outline or some "pseudo code."  (The user should be able to understand
clear, simple sentences preceded by "if," "then," and some version of
"else."  This is a lot like a flow chart, which you can use also, but is
just plain text.)  With an outline, it could be helpful to use hypertext
linking and just provide the mechanism for the user to go to the subsections
s/he wants.  Be sure to include features for getting "back" to the outline.
(I might consider always sending them back to the outline rather than
providing links to the next step in the current step--your call.)  If your
manual will be paper-based, you can simulate hypertext links with just "go
to page X" statements, again being careful to send them back to the outline
at the end of each page x.  At the beginning of the outline or flowchart,
tell the reader to follow it.
 
Now, this could be part one of your manual.  There are users who want a
reference source where they can easily look up a particular subroutine or
whatever.  Part two of the manual can answer this need.  Could be a
collection of "frequently asked questions."  Your SME may be able to suggest
them.  Also feels like an index.
 
These are just some ideas that hopefully will stimulate others.  Feels to me
like the KISS concept works best in documenting complex systems.  It's not
the way to the thinnest manual, of course.