Conference thebay::joyoflex

429.0. "ZEN and the Art of Software Documentation" by CHIC::PETERS (E Unibus Plurum) Fri Oct 30 1987 07:55

                   ZEN AND THE ART OF SOFTWARE DOCUMENTATION
 
           (Translated from the P'u-t'ung hua dialect by W.C.Carlson)
 
 
Editor's Note:  The following are excerpts from the only known treatise on Zen
Software Documentation.   Called  "H'ring-chu-tsu", which literally translates
to  "Ink of Several Insignificant Matters",  this treatise was written in 12th
century  Japan by the scholarly monk  E'm-ie-T'i.   That it discusses Software
documentation  -  predating the advent of software by some 850 years  - is but
another of the mysteries of those who walk the true path.
 
 
On Preparing to Write of Software
 
To prepare for the  writing of Software, the writer must first become one with
it, somtimes two.   Software is untasteable, opalescent, transparent; the user
sees not the software,  so the writer must see through it.   Spend long, quiet
mornings in meditation.  Do not sharpen the mind, but rather blunt it by doing
Zen  crosswords.   (Ed. note:   Zen crosswords are done by consulting only the
"Down" clues; and always in the mind, never on paper.)
 
The mind should be rooted but flexible, as a long stemmed flower faces the sun
yet bends with the wind. Think not of compound adjectives because they tend to
wire  the  mind  in  two  directions.   Rather,  consider the snowflake, which
radiates in beauty in any and all directions.  Partake of strong drink.
 
Do not study the Software; let it study you.   Allow the Software admission to
your mind, but keep it in the cheap seats.   Let it flow around you at its own
pace. Do not disturb or dismay it, but keep it from your private parts because
it tends to coalace there.
 
When the Software is with you, you will know it.  It will lead your mind where
it  should be,  and prepare you for the narcolepsy  that is certain to follow.
You will  know when  the Software is with you,  and so will others.   You will
smile with an inner smile.  Typewriters will frighten you.  You will fall down
a lot.
 
 
On Writing of Software
 
The first exercise in writing Software documentation is the Haiku.   Haiku are
17 syllable poem forms in which many ideas  of a single concept are reduced - 
nay, distilled - into a short, inpressionistic poem.   For example, the Haiku 
for preparing to write of Software goes:
 
                           Emptiness on paper;
                              Fleeting thoughts.
                           Red Sox play at Fenway's
                              Green Park.

By concentrating on the Software's form and function in a concise, subliminal,
truly meaningless Haiku verse,  you have transcended the Software, and you can
then write the true manual.
 
The following Haiku is from a Zen manual on data transmission:
 
                             How swiftly whirls the disk;
			      Data leaps to the floating head
                               And is known.
 
And this on the art of hardware maintence:
 
                              The smell of hot P.C. card,
                                Blank screen, no bell,
                              New parts will be needed .
 
And another Haiku, this one on debugging:
 
                             All the lights are frozen;
                              The cursor blinks blandly.
                             Soon, I shall see the dump.
 
Let the Haiku thoughts  free your mind  from your fingers.   Your fingers will
write what must be written.  Soon you will be in Doc. Prep.
 
 
On the Review Cycle
 
This is the  murkiest  path.   Storms  gather  and disperse around you in many
directions,  none of which are in English.   The path becomes  unclear as many
ideas compete for attention.  Some of them are fatal.
 
But the writer  of  Zen  Software  documentation  fears  not the turbulence of
review cycles.  Let it storm around you  and  be  dry,  warm,  and safe in the
knowledge that you have written the pure manual. Anyway, you know the printer.
You shall in the end have it your way.