[Bioperl-l] The Documentation Project
cjfields at illinois.edu
Mon Aug 24 12:50:05 EDT 2009
We should probably keep some of this discussion on the list, primarily
as I've been running into conflicts with responses on the wiki page.
It's more amenable to discussion. For anyone out there interested,
you should speak up now, this is the best opportunity to do so (we're
considering lack of input assent).
I want to make a a few key points on behalf of the devs. It's
impossible to consistently maintain two active copies of any
documentation (wiki vs docs in the distribution). I have tried
keeping up with this, helping with the 1.5.2 release, and full-on with
the 1.6.0 release, and it's an extreme headache.
From the maintenance point-of-view, this is what I would do:
1) Where possible always link to the official POD (either pdoc or
CPAN) from the distribution. Make the API documentation link very
prominent (I moved it to the docs section in the sidebar). Protect
wiki module pages (in line with the 'one official copy' rule), allow
writable discussion pages for additional, wiki-specific documentation
(which can be added to the official docs as needed).
2) ...or, have a search bar specifically for the module documentation
that links directly to the proper API/PDOC/CPAN page. Not sure how
feasible that is, particularly since we plan on splitting things up a
3) POD-ify any relevant documentation we intend on including in the
wiki that also comes with the distribution (similar to
Moose::Manual). I do not want to repeatedly edit a plain text INSTALL/
BUGS/DEPENDENCIES file to correspond with the wikified version for
every release (nor vice versa).
Long term: (this is my own personal style, YMMV) move all POD to the
end of the file. Add a 'Status' tags to any method docs indicating
implementation status (virtual, stable, unstable, public, private,
etc). Move method POD to it's own section within the main
documentation. Implement a coding style (as mentioned recently on
list using perltidy, but also using proper method names).
HOWTO's are also subject to API changes, but we haven't run into many
issues with those yet, and they're wiki-specific.
On Aug 24, 2009, at 9:37 AM, Mark A. Jensen wrote:
> Hi All,
> I'm starting this journey of 1000 mi (1620 km) with the following
> Please visit and comment.
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
More information about the Bioperl-l