Documentation (and a lot of it, too)

Believe it or not, Microsoft currently has the best user and developer documentation out there (don’t know about Apple because I haven’t used any of their stuff). A couple of years ago, when I was using Windows, I never had any problems with finding the correct documentation for VC++ and friends on MSDN, not to mention the wealth of user docs offered on the M$ website. Administrating the system was painful, but at least there was a database describing how to go through all that pain.

Linux was a breath of fresh air, but apart from the GNU tools docs and KDE docs, very few apps had docs of the MSDN quality. You could very well find a manpage telling you all the commandline options you can pass to the app, or some obscure tutorial on some yellow-text-on-black-background Geocities website from 1994, but not a comprehensive, step-by-step walkthrough of what the application does. I almost killed myself trying to package RPMs for PCLinuxOS, and I still can’t set up my system to automatically fetch GMail for me. This isn’t because I’m stupid or anything, it’s just that all the docs were either cryptic or dated and the only people who knew how to do this stuff were probably the devs themselves.

I’m pointing this out simply because getting ample, high quality documentation early on in the project will make the number of users and developers adopting Haiku as their primary OS twicefold. The number of people adopting a system is proportional to the amount of docs it has.

As of now, Haiku doesn’t seem to have anything apart from these forums and IRC, plus some tutorials written by a few select people (blessed souls, they are ;)). True, that most of the old Be documentation applies to Haiku, but that is subject to change after R1 or maybe R2, when Haiku becomes a bit more mainstream.

Documenting the system now would be a mistake, since things will change at a breakneck pace, but a Wiki of some sort must be opened for public use once R1 comes out. True, that things will still change, but we will have the entire Haiku community to keep an eye on stuff.

Another very important thing, beside API and user docs, is a place to add step-by-step tutorials for newbie devs. This is the number one way to get people working on software for the OS, however primitive it may be. Working through a short tutorial which is light on theory, and having something that works to show for it gives the impatient a lot of pleasure. And who knows, the same impatient wannabe-developer might be working on the kernel ten years later!