[Biojava-dev] Some words about documentation in Biojava1 and other aspects to Biojava2

[Bruno Aranda - Dev]

Hello all!

As Matthew points out, this is a good moment to say our opinion about what
has been done until now and about what we wish to be done or improved in
Biojava v2... I recommend everyone to fill the biojava survey at
http://polwarth.ncl.ac.uk/ with our point of view and actual use of
Biojava. This is one of the best ways to help and contribute! I've filled
it already and, belive me, I survived... :-)

Well, let's start with an endemic problem for Biojava... the documentation!

Documentation
-------------

I think that the lack of documentation is limiting the use of Biojava.
Biojava in Anger and the demos provided are a good start, but I think that
if you are not relatively good at java and have plenty of free time it is
difficult to use most features of Biojava as you have to discover them
directly from the javadocs. I do believe that more examples and use cases
will be helpful.
I think that currently there are more biologists that enter to the world
of computer science, than computer scientists that join biology. From my
personal experience, in our company we have biology graduates that come to
learn bioinformatics. Normally they know little of java, but after some
time I encourage them to use Biojava. They love to cook some of the
Biojava in anger recipes... but then what? It is difficult to do more
complex things, because many people in the research world has a
"scripting" mentality (eg. Perl). I might be wrong, but I think that when
a person who has done some scripts with Perl comes to Biojava (because
he/she has heard that java is more powerful and things like that) after
executing the examples in anger has the belief that he/she has not done
something that can't be done with bioperl. And, of course, is not the
same. I think that some kind of different should exist to introduce some
of the object theory to that marketshare... Maybe this could be as simple
as to create more examples, for instance, to work with sequences and to
demonstrate in some way that this is not a script and you can do with an
object Sequence almost whatever you have in mind...
For people who know more java I think that is missing some kind of
description of the architecture... or at least, there should be more use
cases in the javadocs...
People has to dive in Biojava! (haven't you seen that many people always
consider themselves newbies? I think this is a common thought... All these
newbies have to continue with us!

I am following the development of Biojava 2 and I have to say that,
refering to documentation, there are a few use cases and a document
describing the general organization. This is good! If use cases are well
maintain and new ones are created... it's the way to follow :)

Ok, now, I think that the change of style of the web is a good point. The
former was really old-fashioned as if we were in 2002 yet... Fresh air is
always good... but now let's use it! I know that to maintain webs is
always a burden... but updated news and content is always helpful... The
Documentation API in the web is still the 1.3pre3...
In my opinion to improve the mailing list with another system such a
forum... couldn't be better? I know that a forum is not a good idea and
has been tried before... But when a user has a problem is quite difficult
to find a solution in the current system... How many times people is
asking the same question? Nowadays, there exist pretty powerful forum
systems with search tools and things like that...
However, for development I believe that a mailing list is better...


Web Services
------------
Nowadays, the use of web service has been increasing slowly but steady. I
think that when some issues about security and performance will be fixed,
web services will be used everywhere. Applications tend to be
service-oriented and web services are the entry points! I think that
Biojava      v2 has to adapt to this situation and to be prepared for
distributed systems and web services... This is a good challenge!! And all
this, of course, without loosing the "scripting" simplicity for the
average researcher needs!


Program execution
-----------------
Maybe this is a bit offtopic and I know that many things have been told
about external program execution (blast, clustalw...). But it is a reality
that many people use Biojava to execute such programs and parse its
results... and for applications at that level. I've developed already a
solution for this situation that can be improved of course... It is just
some general parameters... for instance, I have and object BlastParameters
that implement a Parameters interface, that is executed by a
SimpleExecutor class... and the results are a SimpleExecutionReport etc...
in that BlastParameters object I have accessor methods to blast
parameters... I know that this is then platform dependent some extent, but
could'nt be a subproject, or module, or whatever?


Biojava v2 file parsing
-----------------------
Well, I have to say that I like event file parsing and I am happy with
what I've seen until now. It is now much easier to parse bio-files and to
get featured-sequences from them. Congratulations!! However I have only
got results with the embl file and not with the gff one (I've seen genbank
is not implemented yet). I should have been trying to fix that now... but
you see, I like writing mails :P


Well, I think that this is enough for now, and of course, if I can help in
any of those points (or anything else) please tell!

Bruno