[BioC] Bioconductor documentation

[Sean Davis]

While I agree that we can always strive for better documentation, I 
would disagree that the vignettes are superfluous for "everyday" use of 
bioconductor packages.  I have made much use of the limma "user guide", 
perhaps the single most complete piece of documentation outside of the 
R manuals (and these are not specific to a given package).  While I 
agree that some of the "internal" R documentation could be improved 
upon, I'm not sure that we can simply ignore information contained in 
the vignettes and assume that if it isn't in the "internal" 
documentation, it isn't documented.  I would like to see maintainers 
continue to improve upon the already fantastic source of knowledge 
contained in the package vignettes.  I'm not a developer for 
bioconductor, just a user, so my comments are just opinion, but I do 
think the vignettes are an integral source of information, even 
regarding algorithms (but not parameter defaults---I agree with Naomi 
on this point).  I DO think the official stance could be more specific, 
so I, (probably) like Naomi, would like to hear what role 
vignettes/user manuals should play in package documentation, as in 
practice there is wide variability.

Sean

On Aug 29, 2004, at 9:58 AM, Naomi Altman wrote:

> As always, I am grateful to the developers for donating their 
> wonderful software.  However, the issue of why the documentation is 
> hard to use keeps rearing its head, so ...
>
> One of the problems I am finding with the Bioconductor documentation 
> is that it is not sufficiently explicit, so I often need to go into 
> the code to determine what the routine is doing.  As 2 examples,
>
> lmFit (limma) can take as input an marrayNorm object and by default 
> extracts "maM".  But if you type ?lmFit, this is not given in the 
> documentation.  I have not looked at the Vignette to see if it is 
> listed there.  However, I see the vignettes as tutorials - I should be 
> able to find out what a routine does from its internal documentation.  
> The documentation should be explicit about what is extracted from each 
> type of input object and what is output (if this differs by input 
> object).  I might note that this is particularly cogent for limma, 
> since limma works directly with contrasts for 2-color arrays, but 
> requires an extra contrast step for 1-channel arrays.
>
> Similarly, I cannot tell from the documentation for maNorm or 
> maNormMain whether the background values are used in the 
> normalization.  I.e. the documentation should state which component of 
> the input object will be used and how.
>
> Thanks.
>
> Naomi S. Altman                                814-865-3791 (voice)
> Associate Professor
> Bioinformatics Consulting Center
> Dept. of Statistics                              814-863-7114 (fax)
> Penn State University                         814-865-1348 (Statistics)
> University Park, PA 16802-2111
>
> _______________________________________________
> Bioconductor mailing list
> Bioconductor at stat.math.ethz.ch
> https://stat.ethz.ch/mailman/listinfo/bioconductor