Documentation (or the lack thereof)

Check out the yellow labels -- what do the rest of the buttons do?I’m in Seoul, Korea this week teaching one of the ever-popular Asterisk Bootcamp classes.  As luck would have it, my hotel room has the most amazing remote control in the world!  Not only does it control the big ol’ LCD TV and the DVD player, but it also controls the air conditioner and all the lights in the room (including both lights in the bathroom!)

In trying to actually use the remote control, however, I was given a stark reminder of how important documentation can be.  As you probably already know, I try to take an active role in the documentation teams for both Asterisk and the Fedora Project, but never seem to make the time to write as much as I’d like.  As such, I can only hope our documentation efforts are more effective than the yellow labels on my remote control — just documenting the bare minimum and forcing the user to experiment to do anything useful (and very likely getting lost in the process).

(It’s my own personal opinion that this is one of the ways that free/open source software often fails to keep up with it’s commercial rivals; Many open source projects can’t afford to hire technical writers, and if they’re lucky enough to have volunteers do the work, there often isn’t much praise for the hard work and effort that goes into it.)

If this reminder has you feeling the same way I am, why not step up to the plate and help out on the documentation front?  After all, the fearless leader and the rest of the docs crew needs your help!  As the old adage goes… many hands makes light work!  We’d be glad to have you join our ranks.

Published by

jsmith

Jared Smith is very enthusiastic about free and open source software. To learn more about Jared, visit http://www.jaredsmith.net/about/

Leave a Reply

Your email address will not be published. Required fields are marked *