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

[Dave Messina]

Hi Chris and everyone,

The plans sound great.

My only concern would be on point 3, moving some of the wiki docs into the
distros.

- In what format would the docs be in the distros?

Would it be POD? There is rich markup (URLs, code blocks, syntax coloring,
font sizes, etc) available on the wiki that I'd hate to lose.


- Are there discordant versions now?

I agree that we shouldn't maintain separate versions of these, but I thought
the tutorial had been moved completely to the wiki a while ago, and AFAIK,
the HOWTOs are only present on the wiki. I admit, though, I haven't looked
into this extensively.


- Tying the docs to the version of the code they came with

This could be beneficial if we expect people to have a (good) reason to be
using different (read: OLD) versions of the code. But in practice we're
pretty much always going to recommend people use the latest version, right?
In which case having the docs on the wiki (in sync with the latest, greatest
version) would be fairly practical.

Even if there is a good case for supporting older versions of the code and
docs, I don't know that that's enough of an asset to outweigh the downsides
such as loss of rich formatting and having to have some POD->wiki bridge and
keep it in sync.


I raise all the above mostly to ask for more information on that part of the
plan — I suspect you've considered most of my concerns already, so I'm quite
open to seeing a different point of view on this.


Dave








3) I would like to work on moving the HOWTO's and other relevant
> documentation (Tutorial) back into the distributions, maybe in a particular
> namespace (Bio::Manual or similar).  The reason is simple: maintaining
> possibly discordant versions of documentation is unsustainable.  We could
> possibly set up a way of converting POD->wiki for on-line documentation, but
> I would like the documentation be tied to the version of the code it comes
> with, and the only easy way to do so is to package them all together.
>