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.
#1 by Ian Fairman on September 16, 2003 - 1:07 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: http://www.joeyoder.com/papers/) which gives patterns on how to achieve this.
Ian.
#2 by Guillaume on September 16, 2003 - 3:05 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 ….)
bonus:
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?)
#3 by latest zone diet on November 4, 2004 - 1:11 pm
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