Subject: Results of RTFM straw poll

From: [email-masked] (Peter Shenkin)
Date: Fri, 6 Jun 1997 12:59:14 -0400

Last week I posted to CCL a query concerning whether distribution
of hardcopy documentation with complicated software packages, like
MacroModel or Gaussian, in necessary.  Twenty-seven individuals
responded, some to CCL and some by personal email. I promised to
post a summary, and this is it.

The question I was trying to ask was:

	1.  Is it necessary for providers of complicated programs
	such as MacroModel (or Gaussian) to supply hard-copy manuals?

Unfortunately, I didn't state it quite as unambiguously as this,
and although some people addressed this question, others addressed 
other, related questions -- sometimes instead of, sometimes in 
addition to the above.

The other question that was addressed frequently enough to justify
the tallying of results was:

	2.  Is it necessary for providers of complicated programs
	such as MacroModel (or Gaussian) to supply printable (not
	necessarily hard-copy) manuals.  

As I sometimes clarified in email with respondants, I distinguish
a "printable manual" from on-line documentation (such as HTML) in that
the manual has page numbers, an index, a table of contents, and 
(usually) a "nice" page layout.

Since I didn't originally set the questions out as straightforwardly
as above, I had to decide, when reading a response, how to tally it,
if at all.  Someone else might have tallied the results slightly
differently (though, I'd guess, not very differently).

I decided to view (1) as a stronger version of (2):  (2)
asks about printable documentation, but an affirmative answer
to (1) means that not only should there be printable manuals,
but that, in addition, an actual printed copy should be provided.
Thus, I tallied a "Yes" for (1) as a "Yes" for (2) as well;  
similarly, I tallied a "No" for (2) as a "No" for (1): if one 
need not supply even printable manuals, actual printed manuals 
cannot be necessary.  I feel the comments made in the responses 
justify this interpretation.

Poll Results:
			     Necessary	    Unnecessary
1. Hard-copy manuals:		 8		 9
2. Printable manuals:		19		 6

Summary:  More people addressed the question I wasn't trying to 
ask (2) than the one I was trying to ask (1).  But, of those
who addressed each, about 80% think printable manuals are necessary,
but only half think that software vendors need supply actual
hard copy.

Some rationales expressed for some of thae above views:

	Printed manuals (even if printed by the user) are great because 
	you can read them on the bus (or in the toilet).

	Even if you don't choose to read manuals on the bus (or in
	the toilet) yourself, printable manuals allow those who
	wish to to do so.

	Vendor-supplied manuals are better than user-printed manuals
	because vendor-supplied manuals are more compact, better bound,
	and easier to carry around.
	
Other opinions that were expressed on these and other issues include:

	Hard-copy manuals can "walk away", so on-line manuals are better.

	It's easier to search an on-line manual than a printed manual.

	It's easier to browse and annotate a printed manual than an
	on-line manual.

	Environmental considerations should preclude the printing of
	manuals (even by a user).

	PDF (Acrobat) format is the best on-line format, since it can
	look just like the printed manual yet be searchable and
	cross-referenced.

	PDF (Acrobat) format sucks, since if you don't have the fonts
	and the setup just right, which can sometimes be hard to do,
	you can't view the document at all.

	HTML, though it's limited, is so universal that everyone ought
	to use it for on-line documents.

	It would be great to have HTML docs in a form in which you could
	annotate them, and retain your annotations for future viewing.

	SGI's "Insight" books are the best form of on-line documentation
	in the known Universe.

	SGI's "Insight" books suck, and SGI should have stuck to UNIX
	"man" pages.

	Vendors should supply hard-copy manuals as an extra-cost option.

My personal pre-conceptions, opinions, and post-conceptions:

	I started out strongly in favor of both (1) and (2).  I actually
	do read our manuals on the bus (and our competitors' manuals 
	in the toilet :-) ), and it's much easier to handle a more
	compact document.

	I was surprised, of course, that everybody didn't agree with
	me.

	I regard the poll results as being strongly in favor of printable
	manuals.

	I regard the poll results as indicating only a weak interest
	in vendor-supplied hard-copy -- based on both the paucity
	and the divided nature of the response to question (1).
	My sense is that even most of those who like to read hard-copy
	view user-printable manuals as a reasonable compromise.

"By the way:"

	I went back on my promise to count the votes of MacroModel
	users twice. :-)

	Several people indicated an interest in seeing the
	actual responses.  However, since I never asked permission
	to quote those who responded by email, I want to remove
	the attributions from the responses first.  It will take me a
	few days to get around to this.  When it's done, the full
	list will appear in my finger plan, so just try:

		finger [email-masked]

	In about a week, this should return the actual responses.

-P.

**** "Deep Blue can't triumph in the game of life." (NY Times, 5/13/97) ***
* Peter S. Shenkin; Chemistry, Columbia U.; 3000 Broadway, Mail Code 3153 *
** NY, NY  10027;  [email-masked];  (212)854-5143;  FAX: 678-9039 ***
*MacroModel WWW page: http://www.columbia.edu/cu/chemistry/mmod/mmod.html *