Documentation

[cjfields]

We have at least two alternatives to add documentation.

1. Create a HOWTO on the BioPerl web page. The advantage is one can use wiki markup as needed.
2. Have the documentation included. The advantage of this is it allows the github page to act as the HOWTO (GitHib will markup POD). I think the .pod extension has to be used for this. Alternatively, we can use a POD->wiki converter to automate updates to the BioPerl wiki, which (to me) is the best long-term solution. Disadvantage: doesn't allow rich markup.

[fschwach]

I can create a HOWTO page on the BioPerl wiki. I haven't contributed to the wiki before, is it considered acceptable for anyone to just go ahead and add a HOWTO? Do you think it would be ok to say that Primer3Redux is now the preferred wrapper for primer3 in BioPerl? If we place the documentation in the PODs and use a POD->wiki converter (do you have one in mind? I haven't done that yet), where should we put that, as a separate "HOWTO" in the distribution?

[cjfields]

I think it's better to include the docs with the distribution. Place the docs in the Bio::Manual namespace (something like Bio::Manual::HOWTO::Primer3Redux.pod. See this link for an example from the Moose project.

[cjfields]

Forgot to mention the reasoning for that choice: I think it has become critical to tie in pure documentation to whatever version of BioPerl (or any related code) to the distribution, as POD, and on-line docs in the wiki or elsewhere can be updated automatically using the Mediawiki API and a perl library (I have tested this out before just on a query basis). I think we can lock pages for editing only by admins and have a bot run updates from POD to wiki markup.

[cjfields]

@fschwach Not sure if you planned on still doing this (it's been a while). Let me know, as the wiki is now a Github Pages repo so changes can definitely be made if you are still interested.

[fschwach]

Hi @cjfields , yes, it has been a while but I can still do this if it helps. Are we talking about a HOWTO now or the inline POD documentation?

[cjfields]

@fschwach I'm open for whatever's easiest for you, though I can easily add you to the github pages account so you can add the HOWTO there (just sent you the invite).