[Bioperl-l] Plans for the next release (and beyond)

[Dave Messina]

Thanks, Chris.


> [re inline testing]
>


> This pushes the developers a bit to make sure code examples actually pass
> tests.  In particular I have thought about using this with the eutils
> cookbook, just to catch any changes on NCBI's end, but then realized it's
> broadly applicable to other areas as well.


This is a great idea, and goes well with the docs being version controlled
(your point below) along with the code itself.



> However, at least to me there seems to be a fundamental disconnect between
> the code being developed in one repository (github) and the documentation
> being maintained elsewhere (wiki).  In many cases, once docs are placed on
> the wiki they seem to be largely forgotten by the devs once they have
> reached 'completeness'.  Our focus tends to be the code itself, not the
> documentation.  I'm basically looking for ways to resolve that and have
> documentation evolve along with the code, if possible making it testable.
>

Yes, I can't argue. This has been a problem.



>   We should be able to demonstrate via tests that code and examples
> released with a specific version of BioPerl, including those in the HOWTOs
> and the tutorial, should work with that version of the software; anything
> else is a documentation error or a bug.  We can't do that currently.


That would be great.

In the end I'd have to say correct, up-to-date, and testable documentation
is the most important thing. Hopefully, we can find a way to keep the
readability/usability high — which I think pretty much requires richer
formatting — at the same time. Certainly worth trying in any case!


Dave