[Biopython-dev] Plans for Biopython documentation

[Brad Chapman]

Hey all;
I know I've been hearing a lot of rumblings about the state of 
documentation in the current Tutorial and have been trying to think of 
ways to update the docs and also make them easier to keep up to date in 
the future.

The problem with the current large Tutorial are two-fold:

1. It is huge so trying to get into working on it is a serious mental 
exercise.

2. There is lots of useful code and docs in there that do work just 
fine, but some people might dismiss the whole thing as "out of date" if 
they run into something that doesn't work.

To try and handle both problems, I've decided to trim the Tutorial back 
to it's original intention -- a 10 page or so getting started doc, and 
start creating smaller documentation bits that cover specific topics. 
I've already started doing that this week by splitting off the 
Installation documentation from the Tutorial and making the BioSQL 
documentation separate, and hope to continue this as I have time.

What this means practically is that I think when we document new 
modules we should think about them as "standalone documentation bits" 
instead of parts of the huge Tutorial. My current plan is organize 
these on the Wiki page:

http://www.biopython.org/wiki/html/BioPython/BiopythonCode.html

And place the html/pdf/whatever pages in a directory (docs) on the 
biopython.org website so that anyone with cvs access should be able to 
add their own stuff.

This also has additional benefits in that you can write your 
documentation bits in any format you might like and aren't forced to 
use the latex format that I like so much.

Does this seem like a good plan to people to clear up some of the 
documentation messes and get more useful docs out there? Any other 
suggestions or random thoughts?

Brad