[Bioc-devel] Requirment for a Vignette
Robert Gentleman
rgentlem at fhcrc.org
Tue Sep 25 18:53:51 CEST 2007
Hi,
No real disagreement here. I can see where a vignette for something
that is purely infrastructure might not be the best solution. On the
other hand, if it were very short, and pointed to some packages that
actually use the infrastructure, suggesting that developers look at
those (yes you can find this from the web site, but sometimes it is
helpful to know which packages the developer thinks are using their code
properly) I would find that very helpful.
I did want to note that Aedin's observation that things are getting
worse is not true (her numbers show only half as many without vignettes
in 2.1 as in 2.0), and I hope more developers can be coerced into
providing some form of documentation.
User feedback, such as this, and also directly to package maintainers
is helpful, IMHO, as it shows that users do read the documentation and
find it helpful.
best wishes
Robert
Kasper Daniel Hansen wrote:
> 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
>
> _______________________________________________
> Bioc-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>
--
Robert Gentleman, PhD
Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M2-B876
PO Box 19024
Seattle, Washington 98109-1024
206-667-7700
rgentlem at fhcrc.org
More information about the Bioc-devel
mailing list