Archive for March, 2007

Plans are finalizing to finally begin upgrading the Mozilla Developer Center to the latest version of MediaWiki; we’re still running the rather badly obsolete version 1.5.3. This upgrade has been a long time coming, and was in fact attempted once before with rather unfortunate consequences.

That was a learning experience, and we’re planning ahead to be sure things to more smoothly this time.

One of the things we’ll be doing in concert with the MediaWiki upgrade is replacing our breadcrumbs system with a new one that will be easier to use, easier to maintain, and easier to upgrade going forward. I expect that our breadcrumbs will be broken for a while immediately following the MediaWiki upgrade while we work on putting the replacement system into effect, but once that’s done, things should be in much better shape.

We should also be installing some handy MediaWiki extensions (in particular StringFunctions and ParserFunctions) to enable more powerful templates. We’ll be able to do some very snazzy stuff once this is all done, but there may be some oddness during the interim.

I can’t yet give a guess as to when the work will begin, but I’m hoping to make it happen very soon. I’ll blog more as the schedule starts to firm up.

The last few days (and probably going forward for the relatively immediate future), I’ve been working on reading through the requirements lists for Firefox 3 and Gecko 1.9, following something of a spiral-outward approach. I start with the rough feature lists, then look at the associated bugs, blog posts, and so forth, then eventually will be looking at the code itself.

This is the longest and most “unproductive feeling” stage of documentation. Learning enough that you think you know what to document and how to do it. It takes a good bit of time if you want to produce quality documentation (which of course I do).

What typically happens — and this has been the case for essentially every documentation project I’ve ever participated in — is that I have a long gap where I produce little to no documentation, then, suddenly, a large quantity of material starts to flow out rapid-fire.

There are actually a couple of good reasons why that’s how I work.

First is the research and planning I already mentioned.

Second is the simple fact that I’ve learned that it’s usually not a great idea to write documentation until the subject matter has stabilized at least somewhat. Many of the things that will need documentation for Firefox 3 and Gecko 1.9 aren’t done yet. Gecko 1.9 documentation will likely start arriving in the next few weeks, since it’s alpha and reaching a fairly steady state.

As we start ramping up toward working on the documentation for Gecko 1.9 and Firefox 3, I find myself looking at it in a rather different way. When work was ongoing on Firefox 2 documentation, I was just a writer. Now that I’m leading developer documentation, I have to look at the big picture (and actually a whole stack of pictures of various sizes, some of which are blurry, some in black and white, and some of them just downright scary).

To my surprise, the most difficult part of this process is learning how to gauge my productivity again. I’m used to gauging it by how much documentation I write. But right now, I’m so busy planning and reading and investigating that I’m not really doing any writing. So I find myself feeling like I’m not getting anything done, despite the fact that, in fact, I am.

I need to recalibrate my expectations a bit.

I also need to learn how to find things to say when I don’t know what to say. Case in point: this is my first blog post in a week. Not because I’ve not been doing anything, but because it didn’t occur to me to talk about the planning work that’s underway because in my mind that’s not productive time.

That’s silly, of course. I’ll try to do better going forward.

Today I reviewed a few documents, spoke to a possible contractor that would be working on revising and updating our JavaScript documentation, and now I’m taking a break from reading over Firefox 3 related Bugzilla entries to continue working on scoping the documentation effort for that project.

Hopefully as we go into the summer, we’ll have some interns to help with various aspects of the documentation. In particular, we’re hoping to find someone to work on migrating documentation from mozilla.org to MDC, and another to do organizational and investigative work on the wiki; for example, we’d like to have someone figure out what docs are used the most, build a definitive list of what’s missing, do surveys to find out what’s most desperately needed, and so forth.

Work is also ongoing on the internationalization organization front. I talked to himorin today for a while about the tools MDC Japan has for watching for changes to MDC pages in the English wiki as compared to the Japanese version. Sancus and I have also been talking about developing a more general tool for helping to track changes across all localizations.

Ideally we’d have something that would let us keep track of when a change in one language has been reflected into each other language’s wiki.

There are certain complications involved. Automatically detecting when a revision is propagated from one wiki to another is complicated because other changes may be happening in the interim. So you have to rely on editors marking things off on a list, which can be problematic in that people tend to forget to do things like that (I know I do!).

I’d love to hear more suggestions for ways to monitor changes across all languages’ wikis and to track propagation of changes.