Friday, November 28, 2008

A public service announcement

If you are a programmer who is writing code that will be released to the world as open source, this announcement is for you.

If your code will be seen by the world at large, one of your first tasks should be to write documentation. Document all functions as soon as you write them (before is also helpful). Provide samples on how to use code as soon as you finish a module (or earlier, if possible). Do not wait until your 5.0 release. Do not wait until your 1.0 release. Do not even wait until your 0.5 release. Do it as you write your code. The sooner, the better.

Users of your code will thank you profusely if you manage to provide comprehensive documentation along with the actual binaries of reference builds. DO NOT make them have to scour source code or bug developers in IRC channels to figure out a simple task like "get all cards from an address book" or "how do I write a synchronization conduit?"

1 comment:

Sheppy said...

Did you ever know that you're my hero?

Eric Shepherd
Developer Documentation Lead
Mozilla Corp.