[BioC] Bioconductor documentation

[Naomi Altman]

The vignettes are great - perhaps I should not call them "tutorials".  But 
like other documentation of this type (the book "SAS for Mixed Models" 
comes to mind), it is hard to generalize from the examples.  We need both 
the vignettes and the internal documentation.  We need good but explicit 
defaults for the general user, and the option to change these defaults for 
the expert user.

Here is an example where the documentation is OK, but the option to change 
the defaults is too limited.

Both limma and marray allow the user read only a limited set of columns 
from gpr and spot files.  Why not have this as the default, and let the 
user decide if they want to read in other columns? Some of my clients like 
to filter spots based on quantities like the difference between the median 
and mean spot intensity, the sd of intensity, etc.  They currently need to 
flag spots before importing into Bioconductor because they cannot read 
these other columns readily into an marrayRaw object.

--Naomi

At 09:19 AM 8/30/2004 -0400, Sean Davis wrote:
>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

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