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

[Chris Fields]

On Mar 1, 2011, at 8:02 AM, Dave Messina wrote:

> 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.

It would very likely be POD, though I believe there are POD extensions for adding additional markup in CPAN.  We wouldn't necessarily lose the wiki HOWTOs, but they would be only editable via changes to the official docs in github.  My thought is to have wiki pages tied to the latest version in github via POD->wiki, with additional markup added in for syntax highlighting, etc.  Lots of CPAN modules that could help with this, but it needs further investigation.  Might need a HOWTO unto itself :)

One other point: inclusion of docs may also allow easier implementation of inline testing, where synopsis or HOWTO code can be directly tested from POD when specific directives allow for it.  I believe Dist::Zilla has plugins for this, and of course there is Test::Inline:

http://search.cpan.org/dist/Test-Inline/lib/Test/Inline.pm

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.  

> - 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.

The original intent on moving docs to the wiki was somewhat correct: we wanted dynamic documentation that could be marked up for easier reading, better annotation, etc.  Wiki markup and templates has proved more useful than simple POD (HOWTO for Bio::Graphics, for example).  

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.

Lastly, access to critical documentation is now reliant on access to the wiki, which may not always be possible.  We've had several wiki outages over the years and have recently talked about (off-list) migrating some resource away from open bio servers, wikis being one due to maintenance overhead and spam.  We'll always have a centralized website of some sort, I just want to make sure that one has means to access good documentation all the time.  Installing it with the code seems the best way currently, but I'm open to suggestions.

> - 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.

Right, I agree, and I believe the wikis should only contain a very specific version of the docs, probably either the latest CPAN release or master.  However, I'm thinking of cases where users might not be able to get the latest/greatest, perhaps b/c they are constrained in using a specific version: with Ensembl (v. 1.2.3) or via sysadmin restrictions. 

If we consistently point to the official documentation as being on the wiki, we're not tying it to any specific version (unless it's explicitly stated), only what should work with the current version.    The only history is via the edits on the wiki page, which is not associated with anything, just the edits made.  

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.

> 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.

The actual process of including documentation with the code works as the archival process itself (v 1.7 docs go with v 1.7 code, v 2 with v2 code, etc).  And I think there are ways around the lack of rich formatting with POD, just need to look into it more.

> 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

I've thought about it (as you can probably tell) but I think thought is needed about how to approach it.  It might require testing things out a bit first.

chris