Es Tea Double Eye

Very good post on open source documentation via @TheKeyboard » Open Source Is Really About Documentation – Twisted vs. Tornado. Chris Brain’s point in short is:

I think I can give you an executive summary of this blog post: if the documentation for an open source project sucks, nobody but the most hardcore developers will use it.

That couldn’t be more true! The documentation is just about as important as the application. The problem is that it takes time to maintain. Often we as developers are simply too lazy and “will update the documentation later”. I know I am like that, sadly… Will make it next years new years resolution to change that!

I do think that there could possibly be better ways to do documentation. Look at PHP

‘s documentation. It is fairly simple and concise, but I have often found great value in the user comments and examples which you would find underneath every page. I don’t think it is perfect, but it sure helps.

User contributions play a big role in Open Source documentation and developers with blogs often write their examples on their blogs. I end up finding them by searching Google for it, but it would sure help much more if those posts were linked to the documentation. Something to consider, I think.