Date:         Thu, 9 Jan 1997 10:13:49 -0500
Reply-To:     Stephen Baker <Stephen.Baker@UMMED.EDU>
Sender:       "SPSSX(r) Discussion" <SPSSX-L@UGA.CC.UGA.EDU>
From:         Stephen Baker <Stephen.Baker@UMMED.EDU>
Subject:      Manuals  (was Transforming Data)
Content-Type: text/plain; charset=US-ASCII

I agree that SAS has about the most obtuse documentation, however I think
that BMDP had the best.  Their organization I thought was close to
ideal:
 
, each manual had a quick reference chart to procedures with volume
and page numbers on the inside front cover.
 
  Each procedure had it's own "chapter", organized like a scientific
paper with an abstract a table of contents showing where to find various
examples, sections on special topics. detailed information on the
commands specific to that procedure, the order of instructions and a
summary table of the commands.
 
Each procedure is motivated with a discussion of the literature with
appropriate references.
 
The examples are presented with comprehensively annotated output
explaining all output printed and with guidance on interpreting the
results.
 
The section on commands shows clearly the syntax, options, defaults with
clear, unambiguous explanation.
 
The summary tables at the end of each procedure chapter lays out in a
clear table the commands, defaults, instructions for performing multiple
analysises and references to the apropriate section.
 
Bmdp also provided helpful appendices including:
 
guidance on how to deal with extremely large problems on various computer
platforms
 
Formulae and computational algorithms,
 
an appendix on adding user written fortran subroutines
 
an appendix addressing every data set used in the examples.
 
BMDP provides an eleven page section with references to the appropriate
literature.
 
Finally and most commendably, they provide a real index with items
referenced by BMDP nomenclature AND by standard statistical
nomenclature.  I have spent hours trying to find things in the SAS
documentation because I didn't know what SAS called them.  I've even had
to ask SAS-L on occasion after failing to locate things in the myriad of
documentation.
 
The BMDP documentation is comprehensive and essentially complete in two
volumes.  The only exception is that there are some technical reports
available for those who really want to get into it.
 
SAS on the other hand has over 200 manuals, requiring a manual to the
manuals.  Granted that after years of experience you learn where to look
for things.
 
SPSS is unfortunately, heading down this path as well.  However what SPSS
has done is to provide a system for which you seldom need a manual as it
is exceptionally intuitive and well thought through.  The GUI eliminates
syntax errors even while it makes obvious the options and defaults.  I
hope that SPSS moves toward having 100% of it's features accessible
through this interface.  There are still features accessible only through
the Syntax window and elaborate data manipulation needs to be done
through programming.  Here documentation is important.  What SPSS has
done a fairly good job on here is putting it on-line.  When 100% of
SPSS's documentation is available through the Win Help facility using
full text searching (not just limited keywords) then SPSS will have
really made it's system superlative.
 --
 
 
 
Stephen P. Baker                              phone:    (508) 856-2625
Lecturer in Biostatistics                               (508) 856-3131 fax
Department of Academic Computing                        (413) 253-3923 home
University of Massachusetts Medical School    e-mail: stephen.baker@ummed.edu
55 Lake Avenue North                                  -.- -.. .---- .--. ..-.
Worcester, MA 01655                           www:    http://stats.ummed.edu/
GAT/MA(CS)d+/-p-c++lu++e++m--(++)sn+h---fg+w+t+r-y+(*)