Subject: RTFM? What FM? was: Re: CCL:G:Conv=N command in G94

From: [email-masked] (Peter Shenkin)
Date: Thu, 22 May 1997 00:53:28 -0400

Jaime Martell ([email-masked]) wrote:
> From: "Fredrick C. Hagemeister" <[email-masked]>
> > On Wed, 21 May 1997, Chia-Ning Yang wrote:
> > > I happen to forget where to put the command Conver=N in
> > > g94 input file.  Can somebody answer me this?

> > Wherever the G94 manual tells you to put it.  My apology if you don't
> > have a manual, but doesn't Gaussian still supply them with every purchase?
> > It just seems to me that a large portion of the questions asked here
> > could better be answered by searching in manuals...

> I think I understand both sides.  On one hand, yes, I believe that
> people should first try to find an answer through traditional methods
> (manuals/docs and tech. support).  ...
> However, some legitimate Gaussian users may not have
> documentation available.  ...
> 
> I suggest to Chia-Ning Yang to check out www.gaussian.com.  It has a
> more complete version of the docs than the manual they send out!  ...

This little exchange reminds me that the printed manual seems to
be going the way of the <pick your favorite endangered species>.

Many computer products (hardware and software) are now being shipped
without printed manuals.  Often, printable manuals are supplied on
a CD/ROM, but sometimes even this isn't done -- there is only on-line
help, and maybe some HTML pages at a distant site.

What do people think of this?  We still supply printed manuals with
MacroModel, but they're very expensive to print and to ship.  We
also (in version 6.0) supply PostScript and HTML copies of the manuals
on the distribution tape, and the HTML version is also on line at our 
WWW site.  There is also separate on-line help from the GUI.

What if we were to eliminate the hard copy?  Opinions, anyone?  (If
you're a MacroModel user, your vote counts double. :-) )

Seriously, though, I'd like to know what people think about this
trend in general.  Is on-line documentation enough?  Is HTML
enough?  Do we need printable documentation (with page numbers,
table of contents, index, and nice page layout)?  If we do, should 
folks like us supply hard copy, or just let people print their 
own from a supplied PostScript version?

By the way, sometimes people say,  "Well, you could supply hard 
copy as an extra-cost option."  It turns out that this is rather 
hard to do.  It's hard to estimate demand, so either you print small
press runs, which makes things very expensive, or you print large 
press runs but charge enough to cover your costs if you only sell 
half of them, which also makes things very expensive.  And the extra 
variability in the orders adds to the time spent tracking and filling
them, as well as fixing the inevitable errors that will be made.

	-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 *

---

From: greg Landrum <[email-masked]>
Date: Thu, 22 May 1997 08:43:44 -0400

> own from a supplied PostScript version?

From my perspective as a user/programmer, I like online docs
provided they come in some format which is actually useful. 
This excludes formats like:
-Word processor files
-Raw LaTeX/TeX
-either of the above formats translated mechanically into HTML
-PDF (which is just a complete lose)

Nicely arranged and formatted HTML would be just fine, particularly
if it is really searchable (then you don't need to worry abou the
index).  A great combination would be a well structured HTML document 
combined with glimpse to allow searches of all the files.  This
has the added advantage of making index preparation one hell of a lot
easier.  This is a fascinating area where the technology is still
advancing fairly quickly.

Automatically produced HTML just doesn't cut it except for 
things like a reference manual.  I have the manual for my eHT package
online, translated into HTML by latex2html,
http://overlap.chem.cornell.edu:8080/~landrum/bind_manual/bind_manual.html
but I don't consider it a substitute for the printed manual.
It's only really useful to look stuff up quickly without
having to go rooting around to find the printed version.
Of course, since YAeHMOP is free software, I just provide the
ps file (and latex sources) for the manual.  There's no question
of me providing a hard copy.

As an aside, it's not going to make a huge difference in the end,
the fact of the matter is that many/most people aren't going to
read the manual regardless of which format it's in.  

-greg 

--------
greg Landrum ([email-masked])
Graduate Student, Cornell Chemistry
WWW: http://overlap.chem.cornell.edu:8080/~landrum
YAeHMOP home page: http://overlap.chem.cornell.edu:8080/~landrum/yaehmop.html

---

From: [email-masked] (Jeffrey L. Nauss)
Date: Thu, 22 May 1997 10:02:25 -0400

> be going the way of the <pick your favorite endangered species>.

Indeed.  My favorite is a certain large computer company that has all of
their manuals on-line (except for a couple very simple "how-to-set-up"
type manuals).  My questions is what does a user do when the computer
won't boot up? ;-)

> What do people think of this?

I am rather ambivalent on this issue.  The format of the documentation
is less important than the content.  Whatever documentation is provided
should be clear and unambiguous yet detailed enough to help beginners
and experts.  This is the ideal, to be sure, but something to aim for.

> What if we were to eliminate the hard copy?

As long as the documentation was available somewhere else, I see no
major problem.  I would say that, at a minimum, an HTML version
on-line to be installed locally as well as a Postscript version should
be provided.  For the Postscript version, yes it should be printable
"with page numbers, table of contents, index, and nice page layout."
Make it as easy to use and read as possible.  The same goes for the
HTML version.  It should be well organized with hypertext links from a
Table of Contents and from within the document to other relevant
links.

GUI documentation from within the program may be nice but it is often not
acceptable for in-depth reading.  For example, often times, starting the
GUI prevents the user from using the main program.  Thus the user must
close the GUI to implement what they just read.  If an error occurs they
must open the GUI again.  With an HTML document opened outside of the
program or with a locally produced hard copy, the user can follow along
in the manual performing the described tasks.

Another huge advantage of including the Postscript version of a manual
is that additional copies can be produced locally as needed.  Every user
could have their own copy if they are willing to pay for the copying.

HTML and Postscript versions of the documentation are, as I said IMHO,
the minimum documentation that should be provided.  These formats are
ones that I believe the majority of people can use.  Other forms of
documentation such as nroff or RTF files could be included but not by
themselves as they are less commonly used.

However, as I said at the beginning, regardless of what format is used,
the content is of paramount importance rather than the format.
Unfortunately, as I heard Peter Kollman say once, grant agencies pay
for the science not the user interface.  I would include documentation
in that statement as well.

-- 
  Jeffrey L. Nauss, PhD           Telephone: 513-556-0148          
  Dir. Molec. Model. Serv.        Fax:       513-556-9239
  Department of Chemistry         e-mail: [email-masked]    
  University of Cincinnati        URL http://www.che.uc.edu/~nauss

---

From: [email-masked] (Brian W. Beck)
Date: Thu, 22 May 1997 10:01:30 -0700 (PDT)

Peter Shenkin wrote:
> What do people think of this?  We still supply printed manuals with....

	Though I am a high tech junkie, for me there's nothing to beat
	a printed manual when I'm reading on how to perform a particular
	operation. I appreciate (nay, love) the ability to search 
	digital text for the instructions, but then I often pull out
	the manual, flop it down next to my terminal or in my lap at
	lunch and figure out the problem.

	As I see it, the problem doesn't really lie in the failings of
	the digital text though. The digital text is great and far easier
	to manipulate/search/etc. The drawback is in the presentation.

	I can't dog ear my terminal or slip it into my satchel, or
	permanently highlight a certain section, etc.

	(Yes, I know I could carry a notebook computer around and colorize
	 text and put in bookmarks,etc but we all know that it isn't the
	 same.)

	If I had a PDA that could display two pages simultaneously,
	but whose content actually resided on a small disk I plugged in
	to the size. One that you could write on with a stylus,etc,etc.
	(ie. a PDA that simulated a book)

	I don't think this is a problem that software vendors can solve
	(at least not for me without my sim-book), so I vote for both
	a digital and a paper copy of the manual.

	How much extra, say in terms of percentage of total cost,
	do you have to pay for a printed manual? 

	-Brian

-- 
=============================================================================
|   .---------.| Brian W. Beck      |    E-mail Addresses:                  |
|/\ |         || Biochem/Biophysics |        [email-masked]        |
|| \\     WSU || Washington St. Univ|   [email-masked]                  |
|\  -        *|| 639 Fulmer         |  URL  http://elmo.chem.wsu.edu/~brian |
| |           || Pullman, WA, USA   |    VOICE    (509) 335-4083            |
| \___________||       99164-4660   |      FAX    (509) 335-9688            |
=============================================================================

---

From: "Xinjun Hou" <[email-masked]>
Date: Thu, 22 May 1997 11:21:14 -0700

> own from a supplied PostScript version?

It would depends how a user uses a program. For MacroModel/Batchmin, I
 think that a hardcopy manual as well as the html version are indispensable.

Xinjun

-- 

C     Xinjun J. Hou ([email-masked])      Agouron Pharmaceuticals, Inc.
C10110000110100101101110011010100111010101101110010010000110111101110101