[Bioc-devel] Requirment for a Vignette

[Aedin Culhane]

Thanks Wolfgang,
Glad to know.  I have no intention of becoming a guardian of vignettes 
;-))))

Perhaps for packages such as affxparser, a vignette could point to 
another vignette, or even a web site.

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.

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