Zen and the Art

 "If  the human brain was so simple that we could understand  it,
we would be so stupid that we would be unable to."

            ZEN AND THE ART OF SOFTWARE DOCUMENTATION
    Translated from the P'-u-t'ung hua dialect by W.C.Carlson

  Yep.  Another  bit  of  humour taken  from  the  loins  of  the
Untouchables Disk Magazine.  Matt needs to be thanked  again,  so
there.

 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'.    That   it   discusses   Software
documentation -- predating the advent of software by 850 years --
is but another of the mysteries of those who walk the true path.
 This article should be read twice.

On Preparing to Write of Software

 To  prepare for the writing of Software,  the writer must  first
become  one with it,  sometimes 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 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  coalesce
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.

 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,
impressionistic  poem.  For example,  the Haiku for preparing  to
write of Software goes:

                   Emptiness on paper;
                        Fleeting thought.
                   Red Sox play at Fenway's
                        Green Park.

 By  concentrating  on  the  Softwares 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 is on Hardware Maintenance:

                   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 Haikku 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  many directions,  none of which are in  English.   The  path
becomes unclear as many an idea 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.

Editor's Note: If you enjoyed this article,  you may not wish  to
               read the following one.