I write *.Rd files primarily because it helps me think through what I
want the software to do AND because the "\examples" provide any degree
of unit testing I feel I need to create "trustworth software" (to quote
Chambers). The fact that I can then share the resulting package with
others is a marvelous byproduct of this approach to software
development, but not the primary reason I do it. Earlier today, I read
where Hadley had had problems with my code and had to read the help file
carefully to understand how to fix the problem. I immediately wrote to
Hadley inviting more input (and to my collaborator to suggest that the
package be placed on R-Forge to make it easier for people to improve
documentation, etc.).
Adding my $0.02 to Seth's.
Spencer
Seth Falcon wrote:
Writing good documentation is hard. I can appreciate the desire to
find technological solutions that improve documentation. However, the
benefit of a help system that allows for varying degrees of verbosity
is very likely to be overshadowed by the additional complexity imposed
on the help system.
Users would need to learn how to tune the help system. Developers
would need to learn and follow the system of variable verbosity. This
time would be better spent by developers simply improving the
documentation and by users by simply reading the improved
documentation.
My $0.02.
+ seth
--
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph: 408-655-4567
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
