Re: Writing for the avid non-reader.

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Brett E Lee asks about  graphics and programming procedure
documentation:

> How do you use graphics with programming procedures?  Flowcharts are a
> waste of my audiences time. They only want to perform, not understand.  If
> you consider tables to be a graphic element, there is already extensive
> use of graphics even within complicated programming procedures.

This is a sticky wicket; I'm in the middle of a book which explains
complicated applications in the context of extending the functionality
of one of our software products.

I've had good luck with figures showing relationships among modules,
frameworks and data structures in object-oriented code. Explaining the
code itself lends itself less well to graphical exposition, but showing
what happens at the top level when you replace a default method in an
object, when you convert an existing application into an object, when
you write a new object from scratch, and so on has worked pretty well. I
just show basically the top level of what the programmer will achieve
with a general operation in order to provide a context.

I've been using simple geometic shapes: rectangles, little squares,
circles, etc. , combined with text labels and arrows. I represent an
object as a large rectangle, the run method as a smaller rectangle
withing the large one, and the other methods as small squares lined up
like little calculator buttons at the bottom, and showing things being
removed, worked on, replaced, and so forth. Then I show the code and
write about it.

Regarding writing about code, I like to have lots of "code white space",
lots of comments within the code marked with easily spotted delimiters
that explain every section. If I have windowing elements controlled by
code, as in an interface, I show a screen with callouts saying the name
of all of the elements the code contains, and say in the explanatory
text that "the preceding annotated window corresponds to the program
listing for INTERFACE.SCL", or something like that. All my window images
and figures are called out with titles; I have a list of them all in the
book TOC.

Sometimes, I'll put a bulleted preview list before a program listing
saying what the major sections of code are doing, and what to watch for
in the listing itself. I've put lists of variable names and what they
represent both before a program listing and after a program listing.
Putting it before works better for longer programs (more than two pages
of program listing), better to put the table after for shorter code
segments.

If several of the programs exceed 20 lines (or so), I insert line numbers and
refer to code elements in the explanatory text by line number. For books
featuring short code segments, I put little circled numbers by sections
of the code, and explain each one with a numbered list following the
code.

That help? For structured programming, I'd have to look at what you're
doing to suggest a graphic technique, but circled number callouts,
internal commentary, and line numbers in the code followed by referenced
exposition would work no matter what kind of program you deal with, I
suppose.

Good luck.

|Len Olszewski, Technical Writer |"Code in haste, repent at leisure." |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|  - Software Truism                 |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|