[Bioc-devel] Requirment for a Vignette

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