Documentation as the price of open source

[jducoeur]

I love Firefox, really I do. It generally works well for me, and I'm finding the architecture rather elegant. But damn: these people can't maintain documentation to save their lives. As I dig into the official docs for XPCOM (merely the core of the underlying architecture for the whole Mozilla shebang), I find that half the key pages haven't been updated in five years or more, and many of those have annotations like "TBD: fill this in next year when we're done writing this part". It's astonishing that the primary book on the subject hasn't been updated since before Firefox was invented.

Bit by bit, the open source world has begun to internalize the notion that discipline is more important when writing open source code than when writing general commercial software, not less. Now if only it would sink in that the same is true of documentation...

Comments

[lakshmi-amman.livejournal.com]

:) I think it will be a while. While most engineers can realize that discipline is important when it works out to the benefit of agressive laziness... documentation seems a bit more elusive. Any project I've been on accomplished it's documentation by management assigning the documentation and making the engineers do it on a schedule, with reviews and such. Without that corporate hierarchy, I wonder how you'd get engineers to do the writing part...

[jducoeur]

It really is similar to the argument for writing your open source code well: the better a job you do, the more people will be able to take advantage of it. Writing a beautiful system and then not documenting it is self-defeating...

[metahacker.livejournal.com]

It took twenty-thirty years to move from "i" and "g_mxyzptlk()" to "hourIndex" and "getNameOfAlienMenaceFromSixthDimension()"; this both gives me hope that, and a time scale for, the day when good documentation will be as run-of-the-mill as decent variable names are now.

Computer + Comics geekery

[jducoeur]

Granted, I already knew I was a geek, but I think I've hit a new high: I looked at your variable names and had an immediate reaction of, "That's a bug"...

Re: Computer + Comics geekery

[metahacker.livejournal.com]

why, did I get the dimension wrong?

Re: Computer + Comics geekery

[jducoeur]

Yaas -- fifth, not sixth.

(Nothing interesting ever seems to happen in the sixth dimension, or for that matter the seventh. Troublemakers always seem to come from the fifth, or occasionally the eighth. Clearly, we need to establish better interdimensional relations with the calmer trading partners in the sixth...)

Re: Computer + Comics geekery

[metahacker.livejournal.com]

The even scarier thing is, once you pointed out I got something wrong, it was obvious...

Re: Computer + Comics geekery

[fairdice.livejournal.com]

Yaas -- fifth, not sixth.

Those darn programmers and their off-by-one errors.

... or for that matter the seventh.

As a mathematician, I feel an obligation to stand up for seven dimensions. The purely imaginary octonions lead to all sorts of good stuff, for starters.

Google also agrees that the 7th dimension is more interesting than 6 or 8:

n	G(nth dimension)
4	1,680,000
5	823,000
6	56,600
7	85,400
8	75,300
9	19,400

Re: Computer + Comics geekery

[jducoeur]

I'm genuinely surprised. I would have figured that Buckaroo Banzai alone would have kicked the 8th Dimension up into the big time. Just shows how fleeting fame is, I suppose...

Re: Computer + Comics geekery

[learnedax.livejournal.com]

That's what they want you to think! Stay away from those sixth-dimensional creatures, they're bad news. Even if they may be incidentally protecting us from slaughter at the hands of, er, science fiction authors.

Legacy code

[metageek.livejournal.com]

Keep in mind that the core bits of the Mozilla codebase are inherited from the commercial world. IIRC, XPCOM is part of the Netscape legacy; it was probably undocumented when we released the code in 1998.

Re: Legacy code

[jducoeur]

True to some light degree, but less and less so. Even XPCOM has been heavily revamped since the handover, as far as I can tell, and most of the rest has been built up since then. Besides, it's been eight bloody years -- more than enough time to clean up the docs...