[Bioperl-l] on BP documentation

[Chris Fields]

Mark,

One suggestion that i agree with: we need to add API-specific module  
documentation to the site somehow (not just links to CPAN/PDOC).   
There are a few ways to do so; a quick way may be to install something  
like the Mediawiki SecureHTML extension and create a protected  
template (this would be for pdoc, cpan, or both).

Another one is to write up a pod2wiki converter and create API- 
specific pages, then have a bot automate the pages.  A POD extension  
also exists, but we would still need to embed code.  I much prefer the  
extensions than anything else.

chris

On Aug 21, 2009, at 10:12 PM, Mark A. Jensen wrote:

> Thanks to all (six, seven including Rob and his perltidy) who
> responded to this thread. (Lurkers, you are not volunteering
> by responding, honest.) I'm preparing a wiki page (of course)
> with the major points, some further comments, and an action
> plan for your consideration.  Watch this space.
> cheers,
> MAJ
> ----- Original Message ----- From: "Mark A. Jensen"  
> <maj at fortinbras.us>
> To: "BioPerl List" <bioperl-l at lists.open-bio.org>
> Cc: "Chris Fields" <cjfields at illinois.edu>
> Sent: Friday, August 14, 2009 10:32 PM
> Subject: [Bioperl-l] on BP documentation
>
>
>> Hi All --
>>
>> Off-list, an old colleague of mine had this insightful, if damning,
>> comment:
>>
>>> I guess that from my perspective, after doing this stuff for
>>> about 10 years, I personally would prefer to see a "summer of
>>> documentation" for the bio* languages (or at least bioperl, as  
>>> that is
>>> the only one I ever look at).  From my own experiences, and from  
>>> those
>>> of many colleagues, the documentation for bioperl has gone from
>>> mediocre to quite poor in the last few years.  I largely think the
>>> wikification of the docs are to blame for this.   Even SeqIO is hard
>>> to figure out now--it took me an hour the other day to figure out  
>>> that
>>> "desc" returns the full Fasta header, and I had to get that from the
>>> module code + trial-and-error, instead of the online docs.  There is
>>> far too much inside baseball going on in the documentation scheme.
>>
>>> So I worry more about the constant adding of features at the expense
>>> of documenting what is already there.  This is just my 2 cents,  
>>> and it
>>> is disappointing to see a downward trend for bioperl in this regard.
>>
>> I would be really interested in all responses from the list users.  
>> I must agree
>> that BP docs are rather a rat's nest and of varying quality, but  
>> taken in
>> toto (POD, HOWTOs, scraps, bioperl-l, etc.) there is a huge amount
>> of useful and sophisticated information available. I think there are
>> approaches we can take to reorganize and standardize the accession
>> of it to make it more useful and inviting. I disagree with my pal  
>> about the
>> wikification, but I wager that the power of the wiki could be  
>> leveraged
>> to greater advantage (right, Dan?).
>>
>> I think that what we all as developers love is to code, and detest  
>> is to
>> document. Since BP is all-volunteer, and volunteers tend to do what
>> they like -- the beauty of open source, btw -- documentation reorg
>> and cleanup probably must devolve to the Core. I am willing to lead
>> such an effort, which will take some time, and more time the fewer
>> volunteers there are. First let's hear some thoughts, and 'let it  
>> all hang out',
>> as they said in my mom's era.
>>
>> cheers
>> Mark
>>
>> _______________________________________________
>> Bioperl-l mailing list
>> Bioperl-l at lists.open-bio.org
>> http://lists.open-bio.org/mailman/listinfo/bioperl-l
>>
>
> _______________________________________________
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioperl-l