Document your FOSS project!


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.

1 comment
  1. Joe said:

    In Toby’s defense, he said “if you’re interested, dive in”. He wrote that code for himself, made a few notes on it, and put it up on Github for anyone else to take a gander at and see how he did what he did.

    There’s something to be said that if you find it a valuable open source, maybe you could have provided some documentation? Yeah, at the stage in his project it means reading the code – likely the unit tests too – and submitting a patch or patches to the README or maybe your own notes on using it.

    I agree it would be nice and helpful if they all had documentation, and nice and helpful if the code actually followed PEP8 and had some docstrings to explain what was going on, but that code isn’t too big really – and quick to scan the two or three files you’d need to glance through to see what he’s doing and get the gist of how he’s doing it.

    Even just looking at Github, it’s clear that he hasn’t had anyone pull an obvious copy and provide anything back. Maybe what this project is waiting on is someone else to help provide some reason for him to document it outside of his own use…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: