85 lines
3.9 KiB
Plaintext
85 lines
3.9 KiB
Plaintext
|
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'. 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 cert
|
|||
|
|
ain 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 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
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
|