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.