"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
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
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
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;
Red Sox play at Fenway's
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
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.
The text of the articles is identical to the originals like they appeared in old ST NEWS issues. Please take into consideration that the author(s) was (were) a lot younger and less responsible back then. So bad jokes, bad English, youthful arrogance, insults, bravura, over-crediting and tastelessness should be taken with at least a grain of salt. Any contact and/or payment information, as well as deadlines/release dates of any kind should be regarded as outdated. Due to the fact that these pages are not actually contained in an Atari executable here, references to scroll texts, featured demo screens and hidden articles may also be irrelevant.