[Rd] how to document stuff most users don't want to see

[spencerg]

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