[Bioperl-l] Plans for the next release (and beyond)
David.Messina at sbc.su.se
Thu Mar 3 15:52:44 UTC 2011
> [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!
More information about the Bioperl-l