[Bioperl-l] on BP documentation

[Chris Fields]

On Aug 14, 2009, at 9:32 PM, Mark A. Jensen wrote:

> 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?).

To me good documentation should be a combination of both wiki docs  
(HOWTOs, scraps, cookbook-y code) and inline POD.  We can't forsake  
one for the other.  If I had a preference, I would take more up-to- 
date POD over wiki (maybe adding a Status: for the methods), but a  
good HOWTO goes a long way in helping.  It's just too hard to cover  
every use case.

It's unfortunate that documentation is very poor for many modules, but  
at the same time it's also exceptionally hard to write documentation  
for modules one has had no part in developing.  I think this is the  
main reason the docs are in the state they are in (not to point the  
finger of blame at anyone, I'm just as much to blame).

> 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


Two things:

1) Take advantage of the proposed restructuring effort (as well as  
some of the refactoring are doing) to add decent documentation where  
possible.  This means updating method docs and updating the HOWTO's as  
needed, or adding new HOWTO's (Jason has indicated this in the past).

2) Pinpoint areas where docs are desperately needed first.

Other wiki docs could also use updating.  As an example, the above  
author's question on FASTA and desc() is actually answered in the FAQ,  
but the question doesn't make it easy to find:

http://www.bioperl.org/wiki/FAQ#I_would_like_to_make_my_own_custom_fasta_header_-_how_do_I_do_this.3F

chris