home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / week_2.zip / Document.txt < prev    next >
Text File  |  1996-01-07  |  10KB  |  206 lines
  1.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  2.  To:    Esther Schindler [EXEC], 72241,1417Monday, January 01, 1996 5:12:11 AM
  3.  From:    Les Bell, 71210,104        #69847
  4.  
  5. Sorry to have disappeared, but a lightning strike took out my modem and my new Pentium system 
  6. board (wail!). I'm back now, though. . .
  7.  
  8. A few thoughts on documentation quality:
  9.  
  10. 1. On programmers writing documentation: no way! The programmer (especially if there is only one) 
  11. has too many internal assumptions about the product design, and a very different mindset and set of 
  12. aptitudes from the user (unless the product is aimed at other programmers).
  13.  
  14. But the problem is that for many small startups, especially in the OS/2 market, there is simply no-one 
  15. else to do it, except maybe a family member or associate who is willing to work for peanuts. What 
  16. alternative solutions are available? Take a writer into partnership?
  17.  
  18. 2. On-line documentation: OK for secondary documentation. Obviously, installation documentation 
  19. for the OS has to be in paper form, as does the documentation on using the help subsystem and 
  20. documentation viewer. However, until such time as I get a literally _huge_ screen, with no need to 
  21. overlap windows ever, or a system that will activate windows on thought command, I still want paper 
  22. a lot of the time. I agree that having Redbooks on CD-ROM is great for searching, but I vividly 
  23. remember the first time I set up a CID server from on-line docs - an absolute nightmare; the best that I 
  24. could say is that it was needlessly fatiguing.
  25.  
  26. Remember also that Postscript files - a favourite way of distributing docs for later printing - have 
  27. built-in assumptions of page size. Since US letter size is wider than ISO A4, most users outside the 
  28. US will often find lines truncated when he tries to print .PS files.
  29.  
  30. 3. A problem facing some developers is the sheer size and functionality of their applications. Early 
  31. releases tended to have comprehensive documentation, detailing (e.g.) every command or function, 
  32. every mode, etc. However, the spread of rampant feature-itis (in order to fill as many check-boxes as 
  33. possible in those god-awful 'objective' magazine reviews) has meant that maintaining a similar level 
  34. of documentation quality would lead to a) expensive paper documentation and b) a box so big as to 
  35. frighten off prospective users. Visual Age C++ is already heavy enough - the paper manuals I would 
  36. like to have would terrify beginning programmers<g>.
  37.  
  38. So, the vendors have moved the docs into either supplementary manuals (e.g. the MS Word 
  39. Technical Reference) or on-line docs (e.g. the DeScribe macro manual which is now on-line). I'm just 
  40. glad I still have the paper version of the DS Macro Manual - I find trying to _learn_ concepts from 
  41. on-line docs, shall we say, sub-optimal. For a reference, on-line is great, though.
  42.  
  43. Like Esther, I still remember the original Word Perfect manuals as being well organised. 
  44. _Functional_ organisation, with sections like 'How to lay out a letter', or 'How to create a table of 
  45. contents'.
  46.  
  47. In fact, my ideal documentation layout is something like this:
  48.  
  49.     Section 0. Table of Contents
  50.         Section 1. Introduction, Overview and Concepts
  51.     Section 2. Tutorial or Functional sections, organised by 'How do I?'
  52.     Section 3. Reference Sections - listing all commands, functions with arguments, results, 
  53. side-effects, etc
  54.     Section 4. A good, comprehensive, cross-referenced index
  55.  
  56. Section 1 is the most important, and should explain the few fundamental concepts* around which the 
  57. product is based. I vividly remember the original manuals for Ashton-Tate's 'Framework' product. 
  58. This whole program revolved around the concept of 'frames'. Yet it was only after using the product 
  59. for some time that the user would work out for himself the consistencies between the various 
  60. components, at which point a light bulb would appear above his head ("So _that's_ what a frame 
  61. is!"), and the poor user would suddenly make an enormous jump in productivity. The manual never 
  62. actually pointed it out - possibly because to the developers it was so obvious that it didn't need to be 
  63. said! (Thankfully the FW II manual was much improved<g>).
  64.  
  65. * If there are more than a few fundamental concepts, then the product design needs to be looked at 
  66. carefully - documentation is _not_ the problem<g>.
  67.  
  68. If anything has to go on-line, I think I'd plump for the reference material first. If I can read the 
  69. tutorial/explanatory stuff, I won't need the reference much after that anyway.
  70.  
  71. --- Les
  72.  
  73.  
  74.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  75.  To:    Herbert Ice, 72370,2501        Monday, January 01, 1996 6:33:20 AM
  76.  From:    Les Bell, 71210,104        #69849
  77.  
  78. Jay,
  79.  
  80. Have you considered using HyperWise to do your on-line help and manual? One side benefit is that 
  81. you can export the manual as HTML and then make it available on the WWW to aid in your 
  82. marketing, as Chris Graham has done with The Graham Utilities. This way, folks who want to know if 
  83. your product can do something before buying it can check it out easily.
  84.  
  85. --- Les
  86.  
  87.  
  88.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  89.  To:    Les Bell, 71210,104        Tuesday, January 02, 1996 12:36:00 PM
  90.  From:    Herbert Ice, 72370,2501        #69952
  91.  
  92. Les,
  93.  
  94.  Hyperwise is the product that I use. It is one of the few times that I have purchased a product and 
  95. was quite happy with spending the money. I beleive that Steve Weeks uses the product also. Thank 
  96. you for taking the time to respond, much appreciated.
  97.  
  98.  
  99.  Jay Ice
  100.  Iceware Inc.
  101.  
  102.  
  103.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  104.  To:    Herbert Ice, 72370,2501        Friday, January 05, 1996 3:21:25 PM
  105.  From:    Charles Stirling, 100010,1433    #70342
  106.  
  107. Herbert,
  108.  
  109. I do appreciate and understand the idea behind a "staged rollout".  Suspect new aspects would 
  110. come up with each level of user as they are reached.  I also do wonder how you limit it to the 
  111. selected market.  A broad market (which is what I suspect you might actually get, wanted or not) with 
  112. selected outlets might control numbers to give time to iron our and advance it.
  113.  
  114. Will strongly agree not to go for a mass market untill it and you are ready. If customers are lost to 
  115. early in development they can then forever discount something on that first impression never 
  116. realizing how much it has improved.
  117.  
  118. Documentation.
  119.  
  120. "quick reference card".  Sounds excellant.
  121.  
  122. Printed manual.  I'm a great beleaver in the lazer printer for short runs.  It can still look very good, can 
  123. be printed on good standard paper and you can make the changes.  Your $800 quote comes out at 
  124. 5 cents or so a page.  Try 20 copies and see what people say reading it.  Update for the next 20 
  125. copies, etc.  Get some feedback would be my approach.
  126.  
  127. Sort of test marketing at a local frendly shop where you can get "public" to feedback.  Just a thought.
  128.  
  129. Charles
  130.  
  131.  
  132.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  133.  To:    Charles Stirling, 100010,1433    Friday, January 05, 1996 5:51:23 PM
  134.  From:    Steve Weeks, 70541,646        #70348
  135.  
  136.  > Printed manual.  I'm a great beleaver in the lazer printer for
  137.  > short runs.  It can still look very good, can be printed on good
  138.  > standard paper and you can make the changes.  Your $800 quote
  139.  > comes out at 5 cents or so a page.
  140.  
  141. Me too. I have a 140 page User's Manual that works out to about $7.50 each (includes cost of paper. 
  142. toner cartidge, view-binder, disk envelope,  disk sleeve page, other misc. inserts). Weighs about 3.5 
  143. pounds. The binder is the "packaging" ... it ships in a (free) Airborne box for $6.25.
  144.  
  145.  
  146. Steve Weeks - Using VoiceType Dictation for OS/2
  147.  
  148.  
  149.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  150.  To:    Charles Stirling, 100010,1433    Sunday, January 07, 1996 10:22:01 AM
  151.  From:    Shmuel Metz (Atid/2), 71054,3066#70491
  152.  
  153. >> The comment "Anyone who needs to manage or maintain OS/2 systems to the peak of their 
  154. performance" aims the product to high and excludes to many potential purchasers. <<
  155.  
  156. I disagree; they're simply designing a product for a specific market niche. They may well design a 
  157. different product for a different niche. "One size fits all" frequently leads to a Bed of Procrustes".
  158.  
  159.  
  160.  
  161. Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
  162.  
  163.  
  164.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  165.  To:    Steve Pitts, 100331,1134    Sunday, January 07, 1996 10:22:07 AM
  166.  From:    Shmuel Metz (Atid/2), 71054,3066#70492
  167.  
  168. >> But were you sat down in front of a copy and told, here's the manual, learn assembler?? The POP 
  169. is a great reference work, and a useful adjunct to the learning experience, but I'd hate to learn 
  170. assembler with nothing else to guide me <<
  171.  
  172. That's what the assembler language reference is for. Every machine that I've ever programmed for 
  173. I've learned by reading the reference manuals, not tutorials.
  174.  
  175.  
  176.  
  177. Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
  178.  
  179.  
  180.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  181.  To:    Herbert Ice, 72370,2501        Sunday, January 07, 1996 10:22:13 AM
  182.  From:    Shmuel Metz (Atid/2), 71054,3066#70493
  183.  
  184. >> Correct, I had progressed into writing system mods for VM by the time I took my fist 370 assembly 
  185. class. <<
  186.  
  187. Ah, but not just by reading PoOps, which is *not* an assembler language reference. Of course, Steve 
  188. may consider the CMS and CP logic manuals to be even drier <g>.
  189.  
  190.  
  191.  
  192. Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
  193.  
  194.  
  195.  Subj:    Documentation quality        Section: Marketing OS/2 Apps
  196.  To:    Esther Schindler [EXEC], 72241,1417Sunday, January 07, 1996 10:22:19 AM
  197.  From:    Shmuel Metz (Atid/2), 71054,3066#70494
  198.  
  199. >> Most people who want to be experts (in whatever field they choose) are voracious readers, or at 
  200. the least voracious learners. <<
  201.  
  202. Yes, but most users don't want to be experts in the tools that they use.
  203.  
  204.  
  205. Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
  206.