Over a million developers have joined DZone.

Documentation Is Part Of The User Experience

DZone's Guide to

Documentation Is Part Of The User Experience

· DevOps Zone
Free Resource

The Nexus Suite is uniquely architected for a DevOps native world and creates value early in the development pipeline, provides precise contextual controls at every phase, and accelerates DevOps innovation with automation you can trust. Read how in this ebook.

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.


The DevOps Zone is brought to you in partnership with Sonatype Nexus.  See how the Nexus platform infuses precise open source component intelligence into the DevOps pipeline early, everywhere, and at scale. Read how in this ebook


Published at DZone with permission of Chris Odell, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}