It’s the documentation stupid

I think I’ve figured this out. It only took about a month. I’ve setup MovableType, some choice plugins (like MTWeather and MTMacros), a cron job, and PHP Gallery. And boy, was it a pain in the ass.

Open source projects is great, it’s free and wonderful, but it will never approach mass approval because they lack one thing: DOCUMENTATION. You will be hard-pressed to find a Perl script that even has a readme.txt in it. I don’t understand why, except when I did programming, I loathed having to document my code too.

But come on. Some of these scripts don’t even tell you what directory they must be put in. And then they’re the assumptions: that you own your own webhost and have full shell access. That you are a Linux guru. That you don’t require precompiled binaries.

The worse ordeal was getting NetPBM to work. While the MT documentation was terse but informative – as long as you read it several times over – they never mentioned how you could tell it was actually working. And there are no error messages if it doesn’t. And MT doesn’t auto-detect it. It took me several email exchanges with my webhost until we found the right directory it was in.

Then again, if I went the ASP route, the code would probably cost $50 and require Microsoft Access.


In the D drive currently: Racer, an open source OpenGL car simulator. I hesitate to call it an actual game, since it’s primary goal is to simulate the handling and physics of cars as much as possible. Still pretty interesting, if a little buggy at the moment (don’t fall off the track!), and of course, lacking in documentation.