From spencer.graves at prodsyse.com  Wed Oct  7 06:15:27 2009
From: spencer.graves at prodsyse.com (spencerg)
Date: Tue, 06 Oct 2009 21:15:27 -0700
Subject: [Rd] how to document stuff most users don't want to see
In-Reply-To: <20091007034001.GF47890@orange.local>
References: <mailman.17.1254736805.9993.r-devel@r-project.org>	<20091005175041.GB31394@stat.umn.edu>	<77EB52C6DD32BA4D87471DCD70C8D70001E5FD32@NA-PA-VBE03.na.tibco.com>	<4ACA428C.80102@prodsyse.com>
	<4ACAF775.8030708@pburns.seanet.com>	<8ed68eed0910061209u62013017uafd13e4db15d6c3a@mail.gmail.com>
	<20091007034001.GF47890@orange.local>
Message-ID: <4ACC15DF.8090704@prodsyse.com>

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



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