[Bioperl-l] bioperl-db & biosql documentation

[Dave Howorth]

I've just installed bioperl-db and thought I'd offer some comments about 
my experience as a contribution to the project.  The installation went 
well (with the exception of a self-inflicted test failure) so my 
thoughts are centred around the documentation.

There seem to be lots of (fairly) small files that describe different
aspects of bioperl-db and biosql, particularly installation. They are
all incomplete and all give slightly different instructions (e.g for the
version of MySQL 3.23.? that is required).  Most of them don't have
dates or version numbers or authors or any other indication of their
name or origin. It would be better to condense them into a smaller 
number of more comprehensive documents, IMO.

 From the point of view of a bioperl user, it isn't clear why it's 
necessary to go to three/four sites, download separate tarballs etc and 
read as many sets of documentation (biosql, bioperl-db, bioperl, cpan, 
mysql) to do what from the user's point of view should in an ideal world 
all have been transparently installed when 'bioperl' was installed.  The 
current distribution mechanism seems to be designed more for the 
developers' convenience than the users'.


Files
-----
bioperl-db/INSTALL
bioperl-db/README
bioperl-db/README-MYSQL
bioperl-db/docs/HOWTO-MySQL.html
bioperl-db/docs/HOWTO-make_test.pod

biosql-schema/INSTALL
biosql-schema/README
biosql-schema/doc/README
biosql-schema/doc/biosql-ERD.pdf
biosql-schema/doc/biosql.html
biosql-schema/doc/schema-overview.txt
biosql-schema/sql/README
biosql-schema/sql/biosql-ora/README
biosql-schema/sql/biosql-ora/INSTALL

http://bioperl.org/Core/Latest/biodatabases.html


Version numbers
---------------
Why aren't there explicit version numbers? (in the name of the tar file,
for example, or explicitly stated in the README or INSTALL files)


The docs have a number of places where small improvements might be made:

bioperl-db/INSTALL
------------------
1/ Doesn't actually say how to install bioperl-db (ideally make
Makefile.PL; make; make test; make install but in reality more 
complicated because the schema is shipped separately)

2/ It mentions DBHarness.markerdb.conf but it's not clear why. This file 
doesn't appear to be mentioned elsewhere.

3/ Within the conf scripts, these lines mystified me
      # The name of the database within bioperl-db
      # There is right now only one possible value:
      #   'biosql' for the biosql adaptors
      'database'      => 'biosql',
It wasn't clear what the difference is from the previous dbname line. I 
changed the dbname to biosql_test (which is what I had created) and left 
database as biosql, and that worked but I don't know why.

4/ Refers to MySQL 3.23.52

5/ Discusses whether a pre-existing database should be used for testing. 
Allowing the bioperl-db test script to create a temporary database seems
dangerous since it requires the user be given wide-ranging powers over
any database (unless there's a way to allow a user to just create a 
database named '_test_*').


bioperl-db/docs/HOWTO-MySQL.html
--------------------------------
1/ Full marks for author, date and version number!

2/ Document is excellent at creating a warm fuzzy feeling so I 
understood what was going on.

3/ Refers to MySQL 3.23.41, which apparently worked!!!

4/ It does list 'make Makefile.PL; make; make install', but it omits
  'make test'! (which would be after step 7, I guess)


bioperl-db/docs/HOWTO-make_test.pod
-----------------------------------
1/ This says to copy the conf file to the bioperl-db home directory, 
whilst the INSTALL doc says to leave them in the bioperl-db/t directory 
(and that works)

2/ This file should be deleted and the content incorporated in the 
INSTALL doc, IMO. The point about a user name is a useful reminder.


biosql-schema/INSTALL
---------------------
1/ Lots of good stuff about biosql

2/ Also includes stuff about bioperl, including hints about preloading 
the taxonomy tables that isn't available in the bioperl docs themselves 
as far as I can see.


biosql-schema/README
--------------------
1/ Full marks for author, date and version number!

2/ Refers to MySQL 3.23.50


biosql-schema/doc/README
------------------------
1/ This seems just to be a note about how the (obsolete) biosql.html was 
generated, so should be deleted (or stated directly in an updated 
version of biosql.html)


biosql-schema/doc/biosql-ERD.pdf
--------------------------------
1/ A very useful document.

2/ I'm not sure how the version number ties in with that of the 
biosqldb-mysql.sql script, for example.


biosql-schema/doc/biosql.html
-----------------------------
1/ This would be a useful document but it appears to be obsolete (again, 
no version number, but it's inconsistent with the SQL)


biosql-schema/doc/schema-overview.txt
-------------------------------------
1/ This is a very useful file because it provides design description and 
rationale not found anywhere else.

2/ It appears to be obsolete though still useful (no version number)

3/ It could be improved, IMO, if the section headings matched those of 
the coloured blocks in the ERD and if diagrams of the relevant subsets 
of the ERD were used to illustrate it.


biosql-schema/sql/README
------------------------
1/ This file is short and contains some useful information; it's not 
clear why it isn't simply part of biosql-schema/README.


http://bioperl.org/Core/Latest/biodatabases.html
------------------------------------------------
1/ A useful overview.

2/ The link below is broken (the full stop shouldn't be part of the link):
http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/?cvsroot=bioperl.

3/ The links to the Bio::DB::SQL::SeqAdaptor manpage, the 
Bio::DB::SQL::QueryConstraint manpage, the Bio::DB::SQL::CommentAdaptor 
manpage, and the Bio::DB::SQL::BioQuery manpage don't work.


Just to be clear that this is meant to be constructive suggestions: a 
big thank you to everybody who has put in effort on these great projects.

Thanks and regards,
Dave
-- 
Dave Howorth
MRC Centre for Protein Engineering
Hills Road, Cambridge, CB2 2QH
01223 252960