Agile Zone is brought to you in partnership with:

I wrote my first program in Z80A when I was 14 on a ZX Spectrum and ever since I have been hooked. I love writing code of any flavour as well as being passionate about the coding process. I have worked professionally in the software industry for the last 15 years using Microsoft Technologies, and I code at night in PHP, HTML, Javascript and CSS. Chris is a DZone MVB and is not an employee of DZone and has posted 34 posts at DZone. You can read more from them at their website. View Full User Profile

Documentation Is Part Of The User Experience

  • submit to reddit

Writing open source software is a little bit scary. More scary than when I wake up in the morning and take a look in the mirror, and believe me that is scary enough. No, writing open source software is scarier.

If you work as part of a team then the only other people who will ever see your code are your other team members. In my experience unless your code is shockingly bad, little will be said about the quality, at least to your face. And if you are lucky enough to work in a shop where you do code reviews then the quality of your code is even less likely to be criticized.

Working in the open source world is not like this. You write a plugin and release your baby into the world. You hope a bunch of people will download it, and maybe some of them may even write a review or two. But at the end of the day it is in the big wide world for good or bad.

The thing about writing software and especially about writing for open source projects is that the secondary audience becomes an even greater factor. For them you have to make sure that the code is clear and well written. Everything we associate with code of a high quality. Documentation takes on an even more important role.

Much like for the primary audience, the user interface is the system, for a secondary audience, the documentation becomes part of the user experience. If the documentation is poor, or simply lacking, fewer developers will pick up your product and run with it. And in the open source world, this can kill off development quicker than garlic at a vampire convention.

Even if the code speaks for itself you should still create documentation. Something is better than nothing, good documentation is better still.

Do you document your code? If not why not? If you do do you use a particular format or style of documentation? Whatever you do I would love to hear about it so why not think about leaving a comment.


Published at DZone with permission of Chris Odell, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)