[Bioc-devel] Requirment for a Vignette

[Wolfgang Huber]

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