[Bioperl-l] on BP documentation

[Mark A. Jensen]

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