When you’re trying to kick off a passion project that involves software in some way, it can often seem like getting the actual code up and running is the most important step. However, if you don’t also put the effort into making sure your efforts get documented, you greatly reduce the odds of anyone else getting enthused about your project.
Eric Allman, creator of the widely used Sendmail email routing package, emphasised this point in his keynote address at Linux.conf.au 2011 in Brisbane today. Allman created Sendmail in 1983, but it was after he co-authored a book on using the software in 1993 (often referred to as “the bat book” because of its cover) that usage really shot up. The lesson?
It really proved to me that documentation counts big time, much more than I had imagined. Documentation is the key to broad acceptance. I can’t begin to tell you how important documentation is, and sadly, most OS projects still have not figured this one out.
You might not need to write an 830-page book, but if you’ve developed a neat little web app, make sure that you set aside time to describe how it works on the help pages. It can make all the difference. Even for non-software workplace initiatives, explaining why and how makes it more likely that people will do the right thing.