Ignite Your Community: Documentation

written by Geoff Bowers on Saturday, 9 February, 2008 @ 03:02 PM

Documentation is the Achilles heel of many open source communities. At least Achilles got to rage through history before his untimely death -- open source projects are less romantic. For most developers, once you’ve scratched that itch, the thought of spending time not coding but documenting gives you an all over, body rash.

The reality is that few developers document sufficiently on their own without motivation. And just because someone writes hundreds of pages of guff doesn’t mean anyone else can understand it. Elegant code doth not a Shakespeare make.

How many times have you gone to the bookstore and seen "The Missing Manual" for one commercial product or another? These are mostly commercial products with copius amounts of professionally written documentation. What hope is there for your community project?

Anyone can help with documentation; you don’t need to be a developer or even a word smith for that matter. All projects need technical writers, proof readers, and above all editors. You can make a real difference with a modicum of effort.

Documentation: Musty Books

Read it!

Seems obvious but it’s not. RTFM is the frustrated cry of people across the interweb who have written documentation that never got read. Ease their pain.

Become an editor.

Ok, so what they wrote wasn’t all that helpful. Let them know! For those of us writing documentation, many of the details are so seemingly obvious there’s little point writing them down. Small problem; obvious to me, the developer, may be Gobbledygook to you, the user.

Highlight what you don’t understand. Comment on the WIKI, and post your concerns on the forum. Asking for clarification provides a much needed editing service. It’s easy to respond to specific questions. It’s impossible to respond to “the documentation is a festering piece of crap” with anything but scorn and derision.

Documentation: Technical Writers

Write documentation.

This is the big one, but its easier than you think. You don’t have to tackle the whole project, just document those features you use regularly and give examples of what you did. Get the community to read over your notes and encourage them to be editors.

Examples, examples, examples. Most of us learn best by seeing things put into practice. Annotated code can be a great way to convey technical ideas. Short answers to specific problems tend to work better than long, rambling odes to code. And don’t forget, video clips are the high-speed, low effort tutorial of the current age.

Show off what you’ve done; teach people and earn some kudos at the same time.

Related Blog Posts


Permalink: http://blog.daemon.com.au/go/blog-post/ignite-your-community-documentation