View Single Post
Old 04-22-2011, 01:25 PM   #10
Senior Member
Location: Palo Alto

Join Date: Apr 2009
Posts: 213

There's the point that strong documentation and commenting throughout code doesn't tend to yield grant money or result in stronger publications, but I think it does in a tangential way. For example, making it so other people can utilize your program and code more effectively means you're more likely to have it used in their publications downstream. In that sense, it's a good idea to document well.

The other major benefit is it typically leads to receiving many fewer questions on usage that suck up time down the line (assuming you actually support your program, which I have to say most academic bioinformatics developers do a bang up job of in my experience).

Without pointing out specific examples, I can think of a number of programs that will not end up in my publications in the future because they were frankly too hard to use and not well documented enough. One in particular seemed impenetrable despite being incredibly useful in theory--I just had to give up after two days of trying with no email reply to my questions and no strong documentation because it wasn't worth my time.

On the flip side, some positive examples of programs I've found benefiting from strong documentation include Annovar, BEDtools, BFAST, Dindel, GATK, VCFtools (and others). These are all from academic sources (with varying levels of funding and teamwork on them) and despite being fairly complicated programs generally (okay, BEDtools/VCFtools are very straightforward, but still great) I was able to get them up and running very quickly despite a relatively weak background in programming.

Decent documentation probably should be a requirement when academic publishing bioinformatic software. We've all seen those programs where there's a paper, a program, and any questions about the program get referred to the paper, which isn't typically helpful. Hopefully that's been changing because of the above-mentioned advantages to strong documentation.
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