[BioC] Re: vignett

Vincent Carey 525-2265 stvjc@channing.harvard.edu
Tue, 9 Apr 2002 13:16:29 -0400 (EDT)

> which best described the purpose of the vignete for the packages?
> 1 - concise document so that non expert users or R can get started
> 2 - long document describing all that can be done with the package
> 3 - some examples showing off the package to attract people to use it.

here's a personal view.  we will never have a formal
definition, but of the above i think 1 is closest, 3
is OK, and 2 is not what is primarily intended.  but
2 has some relevance.

first note that there may be multiple vignettes per package.

a vignette should be brief.  it should be a self contained narrative.
most likely it should address an application topic from
the point of view of the investigator, rather than
from the point of view of a coder, even though it may
have content that can inspire additional software development.

finally, it should be noted that one of the aims of the
vignette concept was to have something of broader scope than
the examples section of an R doc page that would verify
that all the bioconductor components relevant to a particular
topic are working together as intended.  however this can lead
to long documents and long run times.  the vignette elements
are not well-suited to this requirement at present.