The code is not the documentation

I was working on an ASP.NET Web site the other day and had need of a component to handle a particular task. A bit of poking around on the Web was enough for me to find what appeared to be an excellent candidate: it had all the features I needed, it got good reviews from people, it included source code, and it had a spiffy online demo so that I could see it in action. Heck, it even had an elegant logo with that lickable look that we've all grown to know and love in the last few years.

I sat through the download and ran the Windows installer for the project, and things still looked good. The attention to detail remained very high for an open source project: it prompted me for an install folder, set up a virtual site at the location and port of my desire, and handled the database setup chores. It was only when I went to actually use the component that things started to go a bit awry. Loading the start page from the created virtual site got me an unhelpful administration page. This pointed me at a couple of samples, which consisted of cryptic, uncommented XML.

And that was it. No "read me" file. No help file. No documentation. Apparently I was meant to dig into the source code on my own if I wanted to find out how to actually use this thing. Instead, of course, I uninstalled it, downloaded a similar project with better (any) documentation, and went on my way.

I'm not going to name the first project, because in my experience this sort of thing is all too common. Now, I realize that writing code is fun, and writing documentation is boring - at least for many developers. But try to look at it from the other side of the download link for a while: what's the point of writing code that will never get used? You can give me the most amazing component in the world, and if I can't figure out how to use it, the only thing I'm going to do is wipe it from my hard drive to free up the space.

Documentation for free components doesn't have to be up to Microsoft's standards (which, fashionable though it is to whine, is actually pretty good in most cases). Give me a readme file that gets me started. Give me a couple of sample projects with commented code. Give me a document with a walkthrough that shows how to use the most important properties. That would be enough. But don't expect me to determine telepathically how your code works.


Upcoming Events


Sign up for our newsletter.

I agree to this site's Privacy Policy.