[Bioperl-l] on BP documentation

[Mark A. Jensen]

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