[Bioc-devel] Requirment for a Vignette

[Kasper Daniel Hansen]

On Sep 24, 2007, at 8:26 PM, Aedin Culhane wrote:

> Its useful to "browse packages" on the website and read the linked
> vignette to get a feel for functions in new or devel packages.  Whilst
> reading all of the man pages is one option.  The vignette is a nice
> "easy-access" documentation.

I am certainly a believer in vignettes - when they do something they  
are good for: showing how all the functions in a package work  
together in an analysis. If it is just a listing of simple commands,  
I find them less useful.

In affxparser we have tried to use the "affxparser-package" man page  
to convey an overview of the package (I am not saying we have  
succeeded). I would find it less useful to add a vignette for this  
particular reason - there is the need for overview and then we have a  
selection of rather specific functions. Which a developer should be  
able to read. We would rather improve the man pages than make up some  
vignette that would just be a pdf version of some examples.

But as I said, for analysis packages it makes a ton of sense.

Kasper

> Thanks
> Aedin
>
> Wolfgang Huber wrote:
>>
>> Dear Aedin,
>>
>> thanks for pointing this out, it is an important issue. The  
>> quality of
>> the documentation of a package is a good measure of how much care its
>> author spent on it.
>>
>> An exception may apply to infrastructure packages such as for example
>> "affxparser" that are not supposed to be directly exposed to users -
>> but even for them the programmers that use them might benefit from a
>> vignette.
>>
>> Btw, the vignettes for "cellHTS2" have been checked in two days ago,
>> Google just hasn't noticed :)
>>
>>  Best wishes
>>     Wolfgang
>>
>> aedin culhane ha scritto:
>>> Thanks Robert,
>>> This is great.
>>>
>>> A google search of  "No vignettes available"
>>> site:http://bioconductor.org/packages/2.1/bioc/  returns 8 hits.
>>>
>>> A google search of  "No vignettes available"
>>> site:http://bioconductor.org/packages/2.0/bioc/  returns 15 hits
>>>
>>> I looked in the code of 1 package (plier) and did not see any .rnw
>>> file.      I also tried to open the vignette using the command
>>> vignette("plier")  and this returns
>>>
>>> Warning message:
>>> vignette 'plier' *not* found
>>>
>>> Thanks
>>> Aedin
>>>
>>>
>>> Robert Gentleman wrote:
>>>>
>>>> Aedin Culhane wrote:
>>>>> Dear All,
>>>>> May I ask a little query?
>>>>>
>>>>> Increasingly, there are Bioconductor packages (many core)  
>>>>> without a
>>>>> vignette.
>>>>   I hope not. It is a requirement, and no less of one for core
>>>> packages than for anyone else.  But it is a requirement only for
>>>> release, not devel.  Operationally, we do not take submissions that
>>>> are not for release, so all submissions must have vignettes. But
>>>> many of the core related packages in devel may not have one, and
>>>> most new ones are unlikely to have one until very close to release,
>>>> when we finalize the API we are going to support for the next  
>>>> release.
>>>>
>>>>   We (the core developers) do use the bioc-devel repository as a  
>>>> way
>>>> to share ideas so that things there are often very intermediate,  
>>>> and
>>>> we expect anyone working off of that to be aware of the risks
>>>> involved in using software under active development.
>>>>
>>>>  In just a few days you will see the manifest for the 2.1 release
>>>> change, and all packages that are not scheduled for release will be
>>>> dropped. Once that happens, we will look for missing vignettes, but
>>>> you could send me (either on or off list) a set of the packages  
>>>> that
>>>> you have found without them, and I will start pushing on people to
>>>> produce something.
>>>>
>>>>   But as I am sure you are aware someone can easily circumvent any
>>>> technical requirement we impose, so the only really reliable way to
>>>> push on a developer to provide good documentation, is for their
>>>> users to ask for more.  That also provides some feedback to the
>>>> developer that their code is being used, so that more development
>>>> effort is of benefit.
>>>>
>>>>  best wishes
>>>>    Robert
>>>>
>>>>
>>>>
>>>>> In my own work, I have found several BioC package
>>>>> tutorials/vignettes invaluable.  They assisted me learn
>>>>> Bioconductor, but additional they provide one with a understanding
>>>>> of the objective of a package and a grasp of the order and
>>>>> procedures required to execute its many functions.
>>>>>
>>>>> Has the requirement for a package vignette in Bioconductor  
>>>>> packages
>>>>> slackened?
>>>>> Thanks a million
>>>>> Aedin
>
>
> -- 
> Aedín Culhane
> Research Associate in Prof. J Quackenbush Lab
> Harvard School of Public Health, Dana-Farber Cancer Institute
>
> 44 Binney Street, SM822
> Department of Biostatistics and Computational Biology,
> Dana-Farber Cancer Institute
> Boston, MA 02115
> USA
>
> Phone: +1 (617) 632 2468
> Fax:   +1 (617) 582 7760
> Email: aedin at jimmy.harvard.edu
> Web URL: http://www.hsph.harvard.edu/researchers/aculhane.html
>
> _______________________________________________
> Bioc-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel