It’s sad when an otherwise attractive FOSS project has zero documentation. I’m loathe to use code without documentation, no matter how simple it
seems to be is. By documentation, I mean installation instructions, reference usage examples, and complete (OK, I’ll take nearly complete) information about any turnable knob.
Today’s Undocumented Project Hall of Shame Exhibit A is Sunburnt. Its author describes its rationale in a blog post that practically had me salivating. I want to replace Lucene with Solr, but don’t want to leverage Django’s ORM to do it. Although Sunburnt sounded like the solution, its total documentation turned out to be a ~25-line readme. Good grief. It might be the greatest thing since sliced bread, but I won’t touch it without docs that include a working example.
“Wait, just read the code!” Nuh-uh. Slippery slope, not walk down I.
If you’re giving open-source code to the world, do the right thing and document it. Any project into which you invest your energy, and of which you think highly enough to publish as open-source, is worth the time. Conversely, if you can’t be bothered to document it, it’s crap that’s not worth publishing.