Of Documentation
April 18th, 2004 • General, Rants
I was trying to install Kwiki, it’s a nice piece of software, modular, extensible, clean design, it seemed to had everything I’d need.
Well, almost everything! Kwiki’s documentation is just horrible, it’s default pages tell you nothing about what do and how to do it, they say the site has more than documentation than the shipped pages, but then again, maybe it doesn’t.
Oh yeah, POD, it’s there somewhere, probably the most documented module is CGI::Kwiki, and it’s a very shy documentation, just a couple of words here and there, check it out for yourself.
Sure I know Perl, I speak Perl, but I’m a practical kind of guy, I’d like to spend the whole afternoon customizing and hacking away rather than trying to figure how things work. As a developer, I’d like to have a how-to-hack document, some words about extending functionality, API’s, how modules are linked and other goodies. Unfortunately, most of open-source developers simply ignore the fact that other developers are just a different kind of users, and just like users they need to know what to do and how to do it.
Maybe we all assume that if a project publishes the source then there’s no need to document anything, others can simply read the code and figure out everything. Well no, that’s not true at all, no one likes to spend hours reading the code just to figure out how to install some software, then eventually finds out that this software isn’t suitable, I know I wouldn’t like that.
So, whenever you code something, please remember to document it, it’ll come in handy, trust me.