[Bioperl-l] 0.7 release: tasks & assignments

[Hilmar Lapp]

Brian, thank you so much. I'm very glad that you are willing to take
this over, and I am sure Ewan, Jason, and all current and potential
users think the same way. You are going to do one of the most important
jobs, of which not only the forthcoming release will benefit from.

See a few further comments below.

"Osborne, Brian" wrote:
> 
> Hilmar et al.,
> 
> >>Second, I signed up Brian for creating more and
> >>especially better documentation.
> 
> First, I apologize for not responding earlier, like most of you
> bioperl is a "labor of love", done outside of the 9 to 5. Regardless,
> I accept the job. Though I won't be making the deadline with my own
> task list I imagine it will look something like this :
> 
> - Reread and refamiliarize myself with the modules.
> - Create prioriotized list of modules which could tell me where
> to start. This list will be based on my experience as user, not
> programmer. I'm assuming that all modules should be documented,

Right. I think your experience as a user is the right direction to come
from for this job, because programmers tend to suppose a user to know
what his module is all about and infer a method's purpose from its name.
So, the programmer, in addition to being lazy in documentation, is too
intimate with his code for giving a good road map to it.

> so the list simply tells me where to start, not what to do or not
> to do. Perhaps we'd only want to focus on the very most stable
> modules, in addition.

Probably a good idea, at least initially.

> - Identify some small set of modules whose documentation I can emulate
> (certainly this list will contain modules whose documentation is a
> well balanced mixture of description and example) or offer to others
> as examples.
> 

This is again something people from the list, the users in general,
should be able to help: what were the modules you found best documented
so you were able to get going quickly?

> As I begin to write I'm assuming a few things will happen. One could be
> that authors are asked to document their public methods (should private
> methods all be annotated too?). Another could be that authors could
> be asked to write the "general" documentation of their modules. Certainly

Sure, ask authors to document their public methods, they're supposed to
do so. Private methods shall be documented, too, if it could make sense
or is even intended to be called by a subclass. Otherwise, it would
still be good programming style because it eases maintainence, but
probably we don't ask for it.

As for 'general' documentation, this is an important, but the hardest
and most time-consuming thing if you want to do it right, that is, in a
way that gets users going. It is, however, obviously essential to give
at least you a good idea in which context a module is supposed to be
used, and if you don't have that, ask the author for input.

Ewan probably has made rich experience with questions and problems users
have, as they also held another bioperl-workshop this summer over at
EBI, where expecially documentation issues arose. So, Ewan, what's your
point of view?

And: folks on the list, this is the time to mail your special mad
documentation encounter in bioperl to Brian.

	Hilmar

-- 
-----------------------------------------------------------------
Hilmar Lapp                                email: hlapp@gmx.net
GNF, San Diego, Ca. 92122                  phone: +1 858 812 1757
-----------------------------------------------------------------