[Biopython-dev] Tutorial & Cookbook

[Brad Chapman]

Hi all;

> > 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.

I am for whatever is easiest to maintain. Being long isn't a problem
as people can just skip to whatever they need; reading things online
will be increasingly common.

Agreed with Michiel that minimizing overlap is key. It's the same as
maintaining code; if you have the same thing in multiple places it
is more likely to get out of sync and be confusing. There is a
pretty clear distinction between tutorial documentation and cookbook
examples, so...

> 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.
[...] 
> +1 for the wiki, -1 for another HTML/PDF document.

Same vote for me. I am responsible for the LaTeX file, but if I were
starting it today would do things entirely on the web. The barrier
to contributing is much lower.

> > 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...

This is a good idea; broken examples in documentation are definitely
annoying. If we enforce a common format for cookbook items, then we
could scrape the wiki pages, extract the python code and run it as
part of the tests. The python cookbook could serve as some
inspiration:

http://code.activestate.com/recipes/langs/python/

Brad