September 15, 2003Open Source and DocumentationTed 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 AMComments
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. Posted by: Ian Fairman at September 16, 2003 01:07 AMAnyone knows why ? The key is: I believe that deploying opensource solutions needs mastering that solutions (means you don't need any docs). bonus: 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 PMPost a comment
|