[Bioperl-l] on BP documentation

[Dave Messina]

>
> To me good documentation should be a combination of both wiki docs (HOWTOs,
> scraps, cookbook-y code) and inline POD.  We can't forsake one for the
> other.
>

I think this notion is already kinda there de facto (inside baseball? :)),
but perhaps we should make clear the idea that:

- POD is the reference manual, with each method's capabilities described
comprehensively and in detail.

- The wiki is tutorials (bptutorial, Jason's slides), use cases (HOWTOs and
Scrapbook), and FAQ

And actually all the POD is accessible online from the wiki at
doc.bioperl.org, too (although maybe a little hard to find -- it's under
Developer--API Docs).



> If I had a preference, I would take more up-to-date POD over wiki (maybe
> adding a Status: for the methods), but a good HOWTO goes a long way in
> helping.  It's just too hard to cover every use case.
>

I'd agree with this, too, partly because I think the HOWTOs are in pretty
good shape, covering the most common stuff pretty well, and partly because I
think the reference manual has to be complete, both for a user coming to
find out how to use it and for authors ensuring that their internal model of
how the code works actually hangs together.

Mark, one attack point for a documentation improvement effort would be to
take a survey of the PODs and see how well they are fulfilling the role of a
reference manual.

But part of a good reference manual is knowing how to find what you're
looking for, and indeed I think that's maybe the main overall problem with
trying to document anything as big and complicated as BioPerl. So for me,
the organization of our copious docs might benefit from some attention.

The goal of providing a way to find information better handled by the wiki,
which does searching and crossreferencing much better than POD.

To take your friend's FASTA header example, I might expect to be able to
search for 'FASTA' or 'FASTA header' on the wiki and find something which
guides me to the answer.

A search for 'FASTA' gives a list of pointers, including the 'FASTA sequence
format' page. That page almost gives the right answer (see the Note
section), but perhaps it might be a nice place to say that in BioPerl, a
FASTA sequence is a Bio::Seq, and that the header is $seq->desc and the seq
is $seq->seq. And there could be an equivalent page for the other common
formats, breaking down how the format maps to an object.


[...] it's also exceptionally hard to write documentation for modules one
> has had no part in developing.  I think this is the main reason the docs are
> in the state they are in (not to point the finger of blame at anyone, I'm
> just as much to blame).


Absolutely, and maybe a first step would be to contact the authors of a
module with out-of-date docs and ask for them to fix it, in the same way one
would go to the author with a bug in their code.

Core+volunteers will certainly be needed for organizing the effort and
assessing the state of BioPerl documentation as a whole, but give authors
the opportunity to take care of their code, too.


Two things:
>
> 1) Take advantage of the proposed restructuring effort (as well as some of
> the refactoring are doing) to add decent documentation where possible.  This
> means updating method docs and updating the HOWTO's as needed, or adding new
> HOWTO's (Jason has indicated this in the past).
>

This is a great idea.



> 2) Pinpoint areas where docs are desperately needed first.
>
> Other wiki docs could also use updating.  As an example, the above author's
> question on FASTA and desc() is actually answered in the FAQ,


Absolutely. Maybe some of the FAQs could actually be added back to the
relevant PODs?


Dave