View Single Post
Old 04-25-2011, 06:32 PM   #15
Senior Member
Location: Palo Alto

Join Date: Apr 2009
Posts: 213

Originally Posted by apfejes View Post
Michael: I think you're preaching to the choir - but really, there's a huge difference between documentation for developers and documentation for users. Conflating the two - or trying to discuss them both at once - isn't going to result in a productive set of action items.
I haven't "conflated" anything, though. 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.

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.

Originally Posted by nilshomer View Post
I will throw a suggestion of the top of my head to get the ball rolling. How about an open source software repository, like an bio-app store, which allows for a central repository of cutting edge (not ten release ago) bio-apps that have software that meet (or are ranked on) certain criteria on documentation, code standards, and portability. I am sure a grant reviewer would then find it easy to look up past software and say, person Y always produces well-documented and well-used software. Similarly, a requirement of applying for a grant that includes software is submission and release of software that meets these standards. Accountability and training is the key.
Certainly a central repository for such software would be fantastic. I think it's a great idea, but who would determine the criteria and judge the software and how?

I'm thinking somewhere in between the like button and the help mailing list.

Maybe hand-in-hand with that is a more general and open feedback mechanism. I recognize sites like SourceForge/GoogleCode/GitHub/etc. give you the opportunity to give a rating and feedback, but it's under-utilized and rather primitive from what I've seen. It might be nice to have a breakdown of different features--usability, documentation, error reporting, et cetera--that could be rated (perhaps by identified users/developers rather than random faceless anons). A review system might be nice.
Mendelian Disorder: A blogshare of random useful information for general public consumption. [Blog]
Breakway: A Program to Identify Structural Variations in Genomic Data [Website] [Forum Post]
Projects: U87MG whole genome sequence [Website] [Paper]
Michael.James.Clark is offline   Reply With Quote