[Biojava-l] Preparation for a 1.1 release?

[Thomas Down]

On Fri, Dec 08, 2000 at 10:32:09AM +1300, Mark Schreiber wrote:
> 
> Would it be a good idea if all future contributions to biojava be required
> to meet a standard of documentation?

Probably...  Unfortunately, there's no real way to objectively
assess documentation.  I guess you can write a script to check
that there is a doc comment attached to each public method, but
this says nothing about the quality of information contained
within.

Since the 1.0 release, I've felt that the javadoc on at least
most of the core classes hasn't been too bad -- certainly not
perfect, but each core method does at least have a sane-ish
description.  The bigger problem is lack of `tutorial' documentation.

Yes, we could do with better documentation.  It's quite hard
to judge exactly where the problems are, since I've been working
on BioJava for more than a year.

Short of locking all the developers in a small room with just
a text editor and javadoc, the best way to improve documentation
is for new users not to suffer in silence.  Any questions, PLEASE
send them to the mailing list (even if they're just small details).
You'll get an answer, and it should feed back into improved
documentation.

Happy hacking,

  Thomas
-- 
``If I was going to carry a large axe on my back to a diplomatic
function I think I'd want it glittery too.''
           -- Terry Pratchett