[Biopython-dev] Tutorial & Cookbook

[Michiel de Hoon]

--- On Fri, 4/10/09, Peter <biopython at maubp.freeserve.co.uk> wrote:
> I have been wondering if the "Biopython Tutorial &
> Cookbook" should be separated now - it is getting
> a bit long (which in some ways is a good thing!).

In my opinion, it doesn't matter if the "Biopython Tutorial & Cookbook" is long. I guess that few people actually print this document anyway.

I am in favor of having one "official" documentation for Biopython. If we have one Tutorial and one Cookbook, we'll have lots of overlap between the two, it'll be unclear what should be in the Tutorial and what in the Cookbook, and we'll have to make sure the two are consistent.

A cookbook on the Wiki could be helpful though, and since the Wiki pages can be fixed easily we won't have to worry so much about inconsistencies with the official documentation.

> Maybe we should re-title it as just the "Biopython Tutorial".

That sounds like a good idea.

> Some bits of the current "Cookbook chapter" might be moved
> into the main body of the tutorial (e.g. the alignment
> stuff),

Yes. The cookbook chapter has the same problem as a cookbook document; it's not clear what should go there. A more logical place for cookbook-style examples is at the end of each chapter in the documentation. For example, Bio.Entrez has a bunch of cookbook-style examples at the end of its chapter in the Biopython Tutorial & Cookbook.
Currently, there are not so many sections left in the cookbook chapter; most of them have become full-fledged chapters and were moved out of the cookbook chapter.

> For a separate "Cookbook", we could again use LaTeX for another
> HTML/PDF document (or set of documents) but perhaps just a
> series of pages on the wiki would be more accessible - and much
> easier for people to contribute to?

+1 for the wiki, -1 for another HTML/PDF document.

> On the other hand, it would be very good if all our
> cookbook use cases
> could be rolled into the unit test framework - which
> wouldn't be so
> easy if they live on the wiki.  Something based on doctests
> might work...

Whereas it can be useful if some cookbook examples are part of the unit tests, I don't think it's absolutely required. I see a wiki cookbook more as complementary to the unit tests.

--Michiel.