Following emails/irc chat with roc and bz, let me explain a bit more what I had in mind about the big changes in mozilla... I was tired and frustrated, it was probably difficult to understand. I apologize for that.

Let me first give you an example : suppose you are an experienced c++ coder but a true beginner in Mozilla, and you need to build a xul standalone front-end for an app of yours; you can't rely on xulrunner yet, because it's said to a bit immature for the time being. So you want to build a standalone toolkit-based app like Nvu, Firefox or Thunderbird... You start looking at mozilla/browser, mozilla/mail and then you cry. The makefiles are incredibly complex and almost not commented, most of the files in app directory are hard to understand so you don't really know how to tweak them, you don't know how to divide the preferences into files, what prefs are mandatory or not. I could write quite a long paragraph like that... Said differently, it works but it's almost impossible to reuse it without Jedi training. IT'S MAGIC, don't try to understand it... We deeply miss a highly descriptive "Your standalone XUL-based HelloWorld app in ten minutes" tutorial. And of course, that tutorial must be up-to-date, and document the changes in the way you build an app... The target is xulrunner, I agree. But it's not ready yet, and in the meantime, we need the standalone app way.

The example above was about standalone apps, but the kernel's code is about the same. Our doc system is incomplete (I hope it's not a surprise for you) not centralized. It's distributed over at least a dozen web sites, and I don't count blogs. When xulplanet dies, we all cry. Blogs are not organized for project documentation, even with the help of blog categories. Our code is poorly documented, even if a few people are currently doing a tremendous effort to make devmo grow. Comments in the code are probably listed in the endangered species. Our bugs rarely discuss and detail architectural changes, because they don't really have to do it if nobody comments on the architecture chosen by the implementor ! Checkin comments are too short to be really helpful. #developers is an invaluable help, but it's not a doc. When people are off, the channel is mute.

I'd love to see appear in bugzilla a new flag on patches/bugs, a checkbox saying "doc available on devmo required for this patch/bug". dria, her doc peers and super-reviewers would be the doc dictators, the "doctators", the ones toggling that checkbox. But anyone could also check a "doctator watch" flag to make doctators look at the bug and possibly toggle the "doc required" flag. Patches having that "doc required" checkbox checked would not be allowed for check-in without a corresponding doc in devmo, and devmo only (meaning not on an external site). Patches checked in with checkbox checked and w/o doc would be backed out by doctators. And I'd love to see docs and comments percolate into mozilla/browser and other non-sr'd directories. That may slow down Mozilla evolution, that's 100% true. That's a price good projects are willing to pay to obtain quality. If Mozilla is a platform, then our doc is not for Mozillians only, it's also for people having no knowledge of Mozilla and having to very temporarily dive into our world. Make our world hard to access and understand and they won't try it again, that's for sure. Cool technologies are not cool w/o doc.

Saying this, I am a third-party implementor, and I am currently hitting the lack-of-doc lack-of-comments problem.

Lack of documentation plagues open-source projects. Mozilla is not an exception in that world even if the situation drastically improved during the last twelve months. We started speaking of "Mozilla as a platform" a while ago ; it seems that this vision of the future of Mozilla is, with xulrunner, still valid. With 100,000++ downloads, a lot of third-party implementors look at Mozilla. And whatever we do, we're not enough in the community to help them all. So we need them to be self-reliant. Then we need doc and doc quality. Otherwise, "Mozilla as a platform" is a dead duck and only Mozilla products will remain. The goal should be a web space as wide as MSDN, and better organized. (side note: the wiki is slow, very slow, too slow...)

I hope the above helped a bit clarifying my position. "Qui aime bien châtie bien", as we say in french :-)

Note: comments allowed