View Single Post
Old 04-25-2011, 09:56 PM   #16
apfejes
Senior Member
 
Location: Oakland, California

Join Date: Feb 2008
Posts: 236
Default

Quote:
Originally Posted by Michael.James.Clark View Post
It's your opinion that the two subjects--code comments and user documentation--can't be discussed simultaneously. I disagree--I think both are important components that contribute to the quality of open-source software and, frankly, to how strong of a software engineer/bioinformaticist/team you are. So kudos to you for "over"-commenting and documenting your own code. Were I on your committee, that would count for something in my book.
Thanks Michael. I really appreciate that. (=

I would like to clarify one thing, however. It's not that the two types of documentation can't be discussed simultaneously, but that they shouldn't be discussed simultaneously. One targets developers, one targets users - and both need to be there. Since the thread started explicitly as a comment on the need to document better for future developers, I thought it might be more productive to keep them separate.

In terms of attracting users, the issues are (IMHO) more straightforward: a good manual, functionality and interface. However, All of that documentation needs to be complete for the development community to embrace a piece of software, in addition to the many other factors involved in getting new developers to buy in. (e.g. choice of language, modularity of code, design, development model, ease of contribution, etc.) I'd rather focus on the later set, as that's where the real meat of this conversation seems to be for me.


Quote:
Originally Posted by Michael.James.Clark View Post
And I think our topic here is really that a greater incentive and emphasis should be made on code commenting, unit testing, user documentation, and interaction than is currently being made in the CS/computational biology/bioinformatics academic community.

As Nils said, software engineering 101--the software needs to be accessible to both users and developers, and I do think it should be judged as such.
First, I agree with your point that a greater commitment is required to good code practices in development. No doubt academic code has a long way to go.

Second, I'd still separate the user/developer communities. While bioinformaticians do an ok job of appealing to users (far from good, but the basic elements are there), we do a terrible job of creating community projects, which is what I feel is really holding the field back.

Where the real gains are to be made in bioinformatics are in making better use of developer's time - If we had all 40 people who had written their own ChIP-Seq code working together instead of generating 40 different peak finders, I think epigenetics would really be accelerated as a field. That would have required a serious, coordinated central project or two in which the learning curve for new developers was as small as possible, aka: good code documentation, etc. Think of a single peak-finder core with the ability for different developers/labs to strap on new modules for it, much the same way R has modules... but now I'm starting to digress.

Anyhow, I agree with your other points on both sourceforge and rating systems. Though, I still think Nils' point makes sense: If we had a single collective bioinformatics repository, it would be much easier to build resources like the ones you've described around such a facility. Rating, project evaluations, and more open feedback mechanisms could all be integrated. I suspect by simply enriching for a bioinformatics population you'd find many of the mechanisms better used.

As long as we lack a unified project location (which is encouraged by the academic environment where each lab hosts their own projects), it would be a much greater challenge to integrate all of this. However, I can imagine a bioinformatics portal fulfilling that function.

Perhaps ECO would be interested in adding a new developer specific component to seqanswers?

(And yes, I just said portal - the 90's are going to hunt me down for using such an outdated meme.)
__________________
The more you know, the more you know you don't know. —Aristotle
apfejes is offline   Reply With Quote