September 15, 2003

Open Source and Documentation

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 potential user.

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 your software.

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.

Posted by cedric at September 15, 2003 08:47 AM

I have to agree. Documentation makes a software product. I've used Weblogic and JBoss in the past and, without wishing to sound like a creep, I think the documentation is the key difference between the two not the cost - the Weblogic docs have been excellent in my experience.

For me the best example of a well-documented open source project is Ant. There's lots of explanatory material, a reference to every task and lots of examples. My first reaction when people criticise Ant is a defensive one because if the documentation is great then you can live with any foibles of the software.

As a final note, anyone wishing to get their software used would do well to look over the "Selfish Class" paper by Foote and Yoder (links here: which gives patterns on how to achieve this.


Posted by: Ian Fairman at September 16, 2003 01:07 AM

Anyone knows why ?

The key is:
Writing code could be fun and be done freely on opensource.
Writing documentation is pretty boring and should be payed for that.(maintain documentation is so difficult,too )

I believe that deploying opensource solutions needs mastering that solutions (means you don't need any docs).
Nowaday, everyone are on "why pay for WebLogic as we ve got JBoss free?" and documentation could be one of the arguments.
Even if there is a sold documentation for JBoss, I can remark that people who don't pay for the software, don't pay neither for the documentation ... (and for the support/consultancy/professional services ... perhaps it's the same music, should be asked to MarcF ....)

Why there is no Cedric Beust at the dev2dev conference (at least at Paris)?
(Who do I need to send an email to blame for that?)

Posted by: Guillaume at September 16, 2003 03:05 AM

Hi - I was looking for some political sites with articles on the recent US election and found your nice site. The comments from others on here are pretty good so I just thought I'd add my thoughts also!

Elaine Cooper

Posted by: latest zone diet at November 4, 2004 01:11 PM
Post a comment

Remember personal info?