Documentation Is Part Of The User Experience

DZone 's Guide to

Documentation Is Part Of The User Experience

· DevOps Zone ·
Free Resource

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

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}