[6274] in s-news-athena
documentation of S functions
daemon@ATHENA.MIT.EDU (Dave Krantz)
Fri Jan 27 08:42:47 1995
Date: Fri, 27 Jan 1995 08:04:11 -0500
From: dhk@psych.columbia.edu (Dave Krantz)
To: s-news@utstat.toronto.edu
Cc: dhk@psych.columbia.edu
I've been using S, in various versions, and Splus more recently,
for 14 years as the principal tool for my own data analyses and
have been teaching it all that time to a wide variety of students,
from mathematically unsophisticated undergraduates through statisticians
with many years of postdoctoral experience. I'd like to offer 5
generalizations:
1. S is not easy to learn or teach. As with other skills,
expertise comes gradually, over a period of years.
2. It is worth the effort.
3. It is not wise to waste time wondering why people do not
do this, that or the other--generally speaking, blaming students for
not adopting ideal learning strategies is just a waste of time. You
have to start with where your students are and try gradually to bring
them to where you would like them to be.
4. It is not productive to criticize people for honest
inquiries or confusions revealed in s-news inquiries and submissions.
Pointing out where answers could have been found is useful, but it
should be done gently, with appropriate understanding that it is
not really surprising that documentation often is not used effectively.
5. Most of the materials I have seen relating to S have too
few examples. People learn most easily from seeing a variety of
examples, rather than by assimilating abstract statements. Examples
should be interspersed in text, even in .Help files, and the examples
at the end of documentation sections or chapters should be deliberately
varied to illustrate some of the scope of the syntactic devices and
some of the range of possible applications. It is true that longer
documentation, resulting from many more examples, can be a bit
unwieldy, but skipping examples is much easier than generating them.
Dave Krantz (dhk@columbia.edu)
