All:
We can anticipate some enhancements in documentation when version 4 of the
S language is implemented in S-PLUS. According to John Chambers
("Evolution of the S language",
http://cm.bell-labs.com/cm/ms/departments/sia/project/S/index.html), in
version 4 of the language on-line help will be driven entirely from S
objects, rather than from text files. Chambers writes
"If the user requests documentation for a function and no explicit
documentation exists, S will now construct documentation of the function
call and argument defaults from the function itself. If there are initial
comments in the function definition, these will be used as a description
of the function. Provided programmers just remember to add a few lines of
comments, functions can be usefully documented from their first writing."
I think the last sentence speaks volumes. Most programmers, especially
myself, could do a better job of documenting their code. I have no
experience with version 4 of S, but I am curious to see whether
self-documentation, as implemented and practiced, really is an
enhancement.
Bob Dorazio
USGS, Biological Resources Division
Gainesville, Florida 32653 USA
______________________________ Reply Separator _________________________________
Subject: [S] RE: Documentation
Author: "Gunter; Bert" <bert_gunter@merck.com> at NBS-Internet-Gateway
Date: 5/27/98 2:28 PM
Mr. Calaway:
Thankyou for your candor. Your comment confirms a hunch that I have had -- to
whit: S-Plus does not fully understand that features without full and
accurate documentation are worthless (or worse). Much work is being expended
on new feature development, no doubt; it is too bad that commensurate effort
is not being spent on documentation. Perhaps this is a legacy from S-Plus's
Unix past. In any case, without such effort, S-Plus will not achieve the
market penetration it should. It is enormously frustrating not to have the
information to tell you how things work-- or to have incorrect information.
Your admission of the inadequacy of MathSoft's "limited documentation
resources" and your current difficulties in trying to fix a large backlog of
problems (while your developers are creating yet more) should certainly give
anyone who contemplates purchasing S-Plus pause. If the past is a guide, it
can only get worse. Whatever else may be said about SAS, at least they
document.
Contrary opinions welcome, of course.
Bert Gunter
Biometrics Research
Merck Research Labs
P.O. Box 2000
Rahway, NJ 07065-0900
732-594-7765
"The business of the statistician is to catalyze the
scientific learning process." George E. P. Box
-----------------------------------------------------------------------
This message was distributed by s-news@wubios.wustl.edu. To unsubscribe
send e-mail to s-news-request@wubios.wustl.edu with the BODY of the
message: unsubscribe s-news
-----------------------------------------------------------------------
This message was distributed by s-news@wubios.wustl.edu. To unsubscribe
send e-mail to s-news-request@wubios.wustl.edu with the BODY of the
message: unsubscribe s-news
|