Why does Open Source software lack documentation?

October 6th, 2008 by Afraithe

DocsI think I have found the answer, noone reads it anyway, if you look at the TinyMCE forum, 75%-90% of the questions have direct answers in the documentation (or even the FAQ), and the replies to it is simple “check the documentation” followed by a “brilliant, thanks!”.

In my opinion, TinyMCE is quite well documented, thanks to ppl helping out and keeping it up to date and free of typos. It has taken a lot of time to make this documentation good, and it feels kinda sad that ppl do not take the time to read it.

Everyone does not have the same way of thinking, but at least when it comes down to solving an issue with a 3rd party software, these are the simple steps I follow.

  1. Check the documentation to the product, the readme, install.txt, wiki etc.
  2. Try a few different Google querys to find out if someone else has had the same problem.
  3. Search in forums/mailinglists etc for a solution.
  4. Try to contact someone or post in public forum/mailinglist etc.

Seems like a lot of ppl just skip to step #4 right away.

Well I guess it is better to have than not to have in the end, hopefully some ppl developing more advanced integrations get a lot of help from the API documentation etc.

Posted in Development, Software, Work

6 Responses

  1. Bram.us » Why does open source software lack documentation? Says:

    [...] “Brilliant, thanks!” Spread the word! [...]

  2. Loic Hoguin Says:

    The problem with documentation is that you get more questions from people who don’t read it than feedback from people who use it. But I’m almost sure (and I hope) there’s actually more people using the documentation than not. For the others, maybe a warning can be shown on the forums/mailing list registration page before they post, if it’s not already in place.

  3. Afraithe Says:

    You are of course right, those who do get help from the documentation aren’t exactly noticed anywhere.

    A form of warning might be a good idea for first time submitters, we will see if we add something for that.

  4. Richard Davies Says:

    I think the problem is that most people are lazy. Instead of following the 4 step process you outlined (which happens to be what I also do), most people will go right to the forum to ask a question hoping that someone else will do the work of looking up the answer.

  5. Peter Wilson Says:

    There’s a bit of a chicken and egg situation. Historically – many open-source projects have had little or no documentation and many that have documentation are written by techies for whom writing documentation is not their key skill.

    That is changing – as Open Source has become less niche and more main-stream, gaining acceptance in the real world so documentation has improved. There is that legacy though to overcome.

    We use SpiderMonkey in our project (Mozillas JavaScript engine). Excellent software. Documentation though is very poor – there’s some basic API documentation but as to how to use it, you’re left to trial and error and the forums.

    Of course the other reason is people are just plain lazy!

  6. Websites tagged "software" on Postsaver Says:

    [...] – Why does Open Source software lack documentation? saved by ru1records2009-01-20 – We make software saved by showtime2009-01-20 – Interview: High [...]