[Bioperl-l] The Documentation Project

[Chris Fields]

Mark,

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

chris

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  
> step:
> http://www.bioperl.org/wiki/The_Documentation_Project
> Please visit and comment.
> Thanks,
> Mark
> _______________________________________________
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioperl-l