 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Esther Schindler [EXEC], 72241,1417Monday, January 01, 1996 5:12:11 AM
 From:	Les Bell, 71210,104		#69847

Sorry to have disappeared, but a lightning strike took out my modem and my new Pentium system 
board (wail!). I'm back now, though. . .

A few thoughts on documentation quality:

1. On programmers writing documentation: no way! The programmer (especially if there is only one) 
has too many internal assumptions about the product design, and a very different mindset and set of 
aptitudes from the user (unless the product is aimed at other programmers).

But the problem is that for many small startups, especially in the OS/2 market, there is simply no-one 
else to do it, except maybe a family member or associate who is willing to work for peanuts. What 
alternative solutions are available? Take a writer into partnership?

2. On-line documentation: OK for secondary documentation. Obviously, installation documentation 
for the OS has to be in paper form, as does the documentation on using the help subsystem and 
documentation viewer. However, until such time as I get a literally _huge_ screen, with no need to 
overlap windows ever, or a system that will activate windows on thought command, I still want paper 
a lot of the time. I agree that having Redbooks on CD-ROM is great for searching, but I vividly 
remember the first time I set up a CID server from on-line docs - an absolute nightmare; the best that I 
could say is that it was needlessly fatiguing.

Remember also that Postscript files - a favourite way of distributing docs for later printing - have 
built-in assumptions of page size. Since US letter size is wider than ISO A4, most users outside the 
US will often find lines truncated when he tries to print .PS files.

3. A problem facing some developers is the sheer size and functionality of their applications. Early 
releases tended to have comprehensive documentation, detailing (e.g.) every command or function, 
every mode, etc. However, the spread of rampant feature-itis (in order to fill as many check-boxes as 
possible in those god-awful 'objective' magazine reviews) has meant that maintaining a similar level 
of documentation quality would lead to a) expensive paper documentation and b) a box so big as to 
frighten off prospective users. Visual Age C++ is already heavy enough - the paper manuals I would 
like to have would terrify beginning programmers<g>.

So, the vendors have moved the docs into either supplementary manuals (e.g. the MS Word 
Technical Reference) or on-line docs (e.g. the DeScribe macro manual which is now on-line). I'm just 
glad I still have the paper version of the DS Macro Manual - I find trying to _learn_ concepts from 
on-line docs, shall we say, sub-optimal. For a reference, on-line is great, though.

Like Esther, I still remember the original Word Perfect manuals as being well organised. 
_Functional_ organisation, with sections like 'How to lay out a letter', or 'How to create a table of 
contents'.

In fact, my ideal documentation layout is something like this:

	Section 0. Table of Contents
        Section 1. Introduction, Overview and Concepts
	Section 2. Tutorial or Functional sections, organised by 'How do I?'
	Section 3. Reference Sections - listing all commands, functions with arguments, results, 
side-effects, etc
	Section 4. A good, comprehensive, cross-referenced index

Section 1 is the most important, and should explain the few fundamental concepts* around which the 
product is based. I vividly remember the original manuals for Ashton-Tate's 'Framework' product. 
This whole program revolved around the concept of 'frames'. Yet it was only after using the product 
for some time that the user would work out for himself the consistencies between the various 
components, at which point a light bulb would appear above his head ("So _that's_ what a frame 
is!"), and the poor user would suddenly make an enormous jump in productivity. The manual never 
actually pointed it out - possibly because to the developers it was so obvious that it didn't need to be 
said! (Thankfully the FW II manual was much improved<g>).

* If there are more than a few fundamental concepts, then the product design needs to be looked at 
carefully - documentation is _not_ the problem<g>.

If anything has to go on-line, I think I'd plump for the reference material first. If I can read the 
tutorial/explanatory stuff, I won't need the reference much after that anyway.

--- Les


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Herbert Ice, 72370,2501		Monday, January 01, 1996 6:33:20 AM
 From:	Les Bell, 71210,104		#69849

Jay,

Have you considered using HyperWise to do your on-line help and manual? One side benefit is that 
you can export the manual as HTML and then make it available on the WWW to aid in your 
marketing, as Chris Graham has done with The Graham Utilities. This way, folks who want to know if 
your product can do something before buying it can check it out easily.

--- Les


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Les Bell, 71210,104		Tuesday, January 02, 1996 12:36:00 PM
 From:	Herbert Ice, 72370,2501		#69952

Les,

 Hyperwise is the product that I use. It is one of the few times that I have purchased a product and 
was quite happy with spending the money. I beleive that Steve Weeks uses the product also. Thank 
you for taking the time to respond, much appreciated.


 Jay Ice
 Iceware Inc.


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Herbert Ice, 72370,2501		Friday, January 05, 1996 3:21:25 PM
 From:	Charles Stirling, 100010,1433	#70342

Herbert,

I do appreciate and understand the idea behind a "staged rollout".  Suspect new aspects would 
come up with each level of user as they are reached.  I also do wonder how you limit it to the 
selected market.  A broad market (which is what I suspect you might actually get, wanted or not) with 
selected outlets might control numbers to give time to iron our and advance it.

Will strongly agree not to go for a mass market untill it and you are ready. If customers are lost to 
early in development they can then forever discount something on that first impression never 
realizing how much it has improved.

Documentation.

"quick reference card".  Sounds excellant.

Printed manual.  I'm a great beleaver in the lazer printer for short runs.  It can still look very good, can 
be printed on good standard paper and you can make the changes.  Your $800 quote comes out at 
5 cents or so a page.  Try 20 copies and see what people say reading it.  Update for the next 20 
copies, etc.  Get some feedback would be my approach.

Sort of test marketing at a local frendly shop where you can get "public" to feedback.  Just a thought.

Charles


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Charles Stirling, 100010,1433	Friday, January 05, 1996 5:51:23 PM
 From:	Steve Weeks, 70541,646		#70348

 > Printed manual.  I'm a great beleaver in the lazer printer for
 > short runs.  It can still look very good, can be printed on good
 > standard paper and you can make the changes.  Your $800 quote
 > comes out at 5 cents or so a page.

Me too. I have a 140 page User's Manual that works out to about $7.50 each (includes cost of paper. 
toner cartidge, view-binder, disk envelope,  disk sleeve page, other misc. inserts). Weighs about 3.5 
pounds. The binder is the "packaging" ... it ships in a (free) Airborne box for $6.25.


Steve Weeks - Using VoiceType Dictation for OS/2


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Charles Stirling, 100010,1433	Sunday, January 07, 1996 10:22:01 AM
 From:	Shmuel Metz (Atid/2), 71054,3066#70491

>> The comment "Anyone who needs to manage or maintain OS/2 systems to the peak of their 
performance" aims the product to high and excludes to many potential purchasers. <<

I disagree; they're simply designing a product for a specific market niche. They may well design a 
different product for a different niche. "One size fits all" frequently leads to a Bed of Procrustes".



Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Steve Pitts, 100331,1134	Sunday, January 07, 1996 10:22:07 AM
 From:	Shmuel Metz (Atid/2), 71054,3066#70492

>> But were you sat down in front of a copy and told, here's the manual, learn assembler?? The POP 
is a great reference work, and a useful adjunct to the learning experience, but I'd hate to learn 
assembler with nothing else to guide me <<

That's what the assembler language reference is for. Every machine that I've ever programmed for 
I've learned by reading the reference manuals, not tutorials.



Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Herbert Ice, 72370,2501		Sunday, January 07, 1996 10:22:13 AM
 From:	Shmuel Metz (Atid/2), 71054,3066#70493

>> Correct, I had progressed into writing system mods for VM by the time I took my fist 370 assembly 
class. <<

Ah, but not just by reading PoOps, which is *not* an assembler language reference. Of course, Steve 
may consider the CMS and CP logic manuals to be even drier <g>.



Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I


 Subj:	Documentation quality		Section: Marketing OS/2 Apps
 To:	Esther Schindler [EXEC], 72241,1417Sunday, January 07, 1996 10:22:19 AM
 From:	Shmuel Metz (Atid/2), 71054,3066#70494

>> Most people who want to be experts (in whatever field they choose) are voracious readers, or at 
the least voracious learners. <<

Yes, but most users don't want to be experts in the tools that they use.


Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
