home *** CD-ROM | disk | FTP | other *** search
/ Shareware 1 2 the Maxx / sw_1.zip / sw_1 / JOKES / JOKES_Z.ZIP / ZEN.JOK
Text File  |  1992-01-08  |  4KB  |  88 lines
  1.                ZEN AND THE ART OF SOFTWARE DOCUMENTATION 
  2.  
  3.      (Translated from the P'-u-t'ung hua dialect by W.C.Carlson) 
  4.  
  5.      Editor's Note:  The following are excerpts from the only known 
  6. treatise on Zen Software Documentation.  Called "H'ring-chu-tsu", which 
  7. literally translates to "Ink of Several Insignificant Matters", this 
  8. treatise was written in 12th Century Japan by the scholarly monk 
  9. E'm-ie-T'.  That it discusses Software documentation -- predating the 
  10. advent of software by 850 years -- is but another of the mysteries of 
  11. those who walk the true path.) 
  12.      This article should be read twice. 
  13. On Preparing to Write of Software 
  14.      To prepare for the writing of Software, the writer must first 
  15. become one with it, sometimes two.  Software is untasteable, opalescent, 
  16. transparent; the user sees not the software, so the writer must see 
  17. through it.  Spend long, quiet mornings in meditation.  Do not sharpen 
  18. the mind, but rather blunt it by doing Zen crosswords. 
  19. (Ed. note:  Zen crosswords are done by consulting only the "Down" clues; 
  20. and always in the mind, never on paper.) 
  21.  
  22.      The mind should be rooted but flexible, as a long stemmed flower 
  23. faces the Sun yet bends with the Wind.  Think not of compound adjectives 
  24. because they tend to wire the mind in two directions.  Rather, consider 
  25. the snowflake, which radiates in beauty in any and all directions. 
  26. Partake of strong drink. 
  27.  
  28.      Do not study the Software; let it study you.  Allow the Software 
  29. admission to your mind, but keep in the cheap seats.  Let it flow around 
  30. you at its own pace.  Do not disturb or dismay it, but keep it from your 
  31. private parts because it tends to coalesce there. 
  32.  
  33.      When the Software is with you, you will know it.  It will lead your 
  34. mind where it should be, and prepare you for the narcolepsy that is cert 
  35. ain to follow.  You will know when the Software is with you, and so will 
  36. others.  You will smile with an inner smile.  Typewriters will frighten 
  37. you.  You will fall down a lot. 
  38.  
  39.      The first exercise in writing Software documentation is the Haiku. 
  40. Haiku are 17 syllable poem forms in which many ideas of a single concept 
  41. are reduced  -- nay, distilled -- into a short, impressionistic poem. 
  42. For example, the Haiku for preparing to write of Software goes: 
  43.  
  44.                    Emptiness on paper; 
  45.                         Fleeting thought. 
  46.                    Red Sox play at Fenway's 
  47.                         Green Park. 
  48.  
  49. By concentrating on the Softwares form and function in a concise, 
  50. subliminal, truly meaningless Haiku verse, you have transcended the 
  51. Software, and you can then write the true manual. 
  52.  
  53. The following Haiku is from a Zen manual on Data Transmission: 
  54.  
  55.                    How swiftly whirls the disk; 
  56.                    Data leaps to the floating head 
  57.                    And is known. 
  58.  
  59. And this is on Hardware Maintenance: 
  60.  
  61.                    The smell of hot P.C. card, 
  62.                      Blank screen, no bell, 
  63.                    New parts will be needed. 
  64.  
  65. And another Haiku, this one on Debugging: 
  66.  
  67.                    All the lights are frozen; 
  68.                    The cursor blinks blandly. 
  69.                    Soon, I shall see the dump. 
  70.  
  71. Let the Haiku thoughts free your mind from your fingers.  Your fingers 
  72. will write what must be written.  Soon you will be in Doc. Prep. 
  73.  
  74. On the Review Cycle 
  75.  
  76.      This is the murkiest path.  Storms gather and disperse around you 
  77. many directions, none of which are in English.  The path becomes unclear 
  78. as many an idea compete for attention.  Some of them are fatal. 
  79.  
  80.      But the writer of Zen Software documentation fears not the 
  81. turbulence of review cycles.  Let it storm around you and be dry, warm, 
  82. and safe in the knowledge that you have written the pure manual. 
  83. Anyway, you know the printer.  You shall in the end have it your way. 
  84.  
  85. Editor's Note:  If you enjoyed this article, you may not wish to 
  86.                 read the following one. 
  87.         (REAL PROGRAMMERS) 
  88.