[Rd] how to document stuff most users don't want to see
spencer.graves at prodsyse.com
Wed Oct 7 06:15:27 CEST 2009
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
Adding my $0.02 to Seth's.
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
> 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
More information about the R-devel