Ted and a few other
people (see the comments) are complaining about the quality of Open Source
documentation. They are not alone.
Here is a typical example.
On a regular basis, I see an announcement for a new utility show up on
JavaBlogs or some other news source. I immediately click on it and very
often, the link is merely taking me to the home page of the project on
sourceforge. That’s already a bit frustrating, but okay, fine. My
reflex then is not to click on the "files" link, nor "lists", nor to
check out the CVS repository.
I click on "Documentation".
And 99% of the time, that page is empty.
At this point, I just close the tab and move on, and you have just lost a
If you are going to post an announcement for your project, you need to take
some time off coding and write up a document. It doesn’t need to be
extensive, it doesn’t need to be perfect, but just like Jason, Ted and others, I
don’t have the time to read your source code. I will be very happy to have
it handy if I need to debug something in your code one day, but until that day
happens, your documentation is all I need.
Explain what problem you are trying to solve, how you solve it and how to use
But there is more to writing documentation. To me, a developer who
spends some time trying to communicate her work other than through code shows
that she has some perspective. She is not just "all code". She
understands users are a different breed and that you need to interact with them
if you are really trying to solve their problem, as opposed to just "scratching
a technical itch" because it’s fun and then pretending you have a product.
Admittedly, documentation written by developers is rarely good, and after a
certain point, you do need technical writers. But for the SourceForge kind
of project, it’s more than enough and it shows the world that you are not just a
hacker: you are a developer, and you remember who you are working for.