[BioPython] BioSQL documentation -- request for feedback

[Brad Chapman]

Hey everyone;
As some of you may know Jeff, Andrew and I are currently in tropical  
Singapore at this year's annual BioHackathon. Working hard for  
Biopython, all thanks to the kindness of Apple Computer Singapore (buy  
an Apple, buy an Apple; no, I've not sold out :-). For anyone who wants  
to follow, there is blogging and pictures at:

http://blog.open-bio.org/biohack2003/

But, the point of this mail is that we are currently working away at  
making BioSQL better and easier to use so that by the time we leave  
we'll have a nice easy together thing for people to use. Tops on the  
list of things to do is documentation, which I've been working on.

Since we've got something nearly ready to go, I thought I would solicit  
feedback from any interested parties on what we've got. Since I've got  
time and am working on this right now, it's the best time for things  
that need fixing, and I'd be happy to get any kind of feedback from  
people on how well things are explained.

So, there are a couple of ways to get the current documentation, which  
is in anonymous CVS on the open-bio machines. You can use anonymous CVS:

$ cvs -d :pserver:cvs at cvs.open-bio.org:/home/repository/biosql login
(Logging in to cvs at cvs.open-bio.org)
CVS password: <the password is 'cvs'>
$ cvs -d :pserver:cvs at cvs.open-bio.org:/home/repository/biosql co  
biosql-schema

Or you can download what we've got as a tarball from the CVS web  
interface:

http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/biosql-schema/ 
?cvsroot=biosql

Either way, in the doc directory are three different docs to check out:

doc/install.txt -- Written by Ewan, this describes the basics of  
installing a database and loading the BioSQL schema.

doc/schema-overview.txt -- Written by Aaron, this describes the SQL  
schema.

doc/biopython -- Written by me, this describes Biopython with BioSQL.  
The directory contains a python_biosql_basic file, which is available  
in pdf, html or plain ol' text, along with the GenBank file used in the  
example.

At any rate, I'd be very happy to get any kind of feedback from people  
on how useful the docs are, where they are confusing/unclear/whatever,  
and that kind of thing. Anything from new users to people who have used  
it before would be great and would give us the chance to have something  
good by the time we are finished with the week.

One side note. If you are inspired by the docs to use this and test it  
out, the SQL schema in CVS is currently in serious flux and doesn't  
work with biopython right now (another thing that will be fixed by the  
end of the week). You should use the SQL schemas in Biopython, stored  
in the Tests/BioSQL directory. Just a caveat with it all being a  
current work in progress.

Thanks in advance for any feedback people can provide.
Brad