Deep Geeking

I was looking at the docs for the brand new Microsoft Silverlight platform. To quote Microsoft...

Microsoft Corp. today released to the Web (RTW) Silverlight™ 1.0, a cross-browser, cross-platform plug-in for delivering richer user experiences on the Web.

Silverlight is much like Adobe Flash, a plugin that allows one to run a GUI in browser. Competing open source technologies might be Gnash, the Flash replacement, client-side Java, the various AJAX toolkits, and lots of custom Javascript solutions.

Just looking at the developer page, I am in awe of how much Microsoft rocks as a company. After all this time, they have it all down pat.

What make Microsoft great, more than anything else, is their ability to churn out the documentation. This platform has only just hit 1.0, and yet on the msdn site you can find complete developer docs, examples, whitepapers, and blogs about the ongoing development. They answer all the critical questions: what it is, what it is good for, where to get it, how to develop for it, and what the future holds. And what makes GNU technologies suck, more than anything else, is their inability to work the documentation. The reason is simple. Doing documentation is boring, and most people would have to be paid to do it.

I know this to be true. I've written a fair amount of technical documentation in the past. In the closed source world, the Wide Area Augmentation System's analysis of Hazardously Misleading Information is a good example. I wish I could give you a link to it. It is impressive, obscure, difficult, and is an example of the type of work that is only possible when someone is ponying up the cash. That pain-in-the-keister took a nationally-distributed team of experts multiple years to assemble, and the sections that I had the privilege to write or edit or wrangle were long, hard, boring, and safety critical. In the open source world, my now-obsolete book on Guile is a typical offering. I worked on it for a while, got bored, gave up, and found something better to do. I know that thousands of people have read it. I've only received one comment on it ever, and without any sort of happy-feelies (the currency of open source) I can't see spending any Saturday afternoons working on it, when I could be outside instead.

GNU/FSF is totally aware that documentation is its Achilles heel. Richard Stallman wrote a good essay about it.

In my spare time, I've been working on a toy program in Guile Scheme, and, as always, I find development takes far longer than expected. This language, like all minority languages, lacks ready libraries, and before I can begin coding the program, I have to create two libraries that would already be available on any "useful" language. For Guile, the Curses library is somewhat bit-rotted and lacking in documentation, and the UTF-8 support is non-existent. As long as I'm in there, I should make these libraries complete and useful as stand along projects.

So I've been pushing my way through wrapping the Curses library. Coding: easy, fun. Unit test and documentation: boring, boring.

That is the great irony of open source. It is legally so much easier to reuse and recycle OS code, but, it is practically impossible. Millions of lines of brilliant code never get reused because reading code is hard, and starting over is oh so tempting.