Mar 012007

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 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.

 Posted by at 5:18 PM

  6 Responses to “Learning curves”

  1. I have the same problem with regards to recalibrating expectations. My job now involves a *lot* of reading, writing, and responding to email, but I still have a mental block when it comes to considering that “real work”. Same issue with planning-related stuff, which is possibly more damaging since my job is pretty much *all* planning now. The result: I haven’t blogged about work-stuff in ages and at the end of the week there’s not a whole lot I can point at and say, “I did this”.

    I’m sure we’ll both get better at this stuff as we go :) In the meantime, I say “three cheers for sheppy”. You’re doing great work and taking MDC docs to a higher, smarter level.

  2. Maybe that’s a common human nature to consider only a creative activities as an actual work. It’s funny, we left hard work for machines and now, we complain again. Relief is behind the corner – Google’s working on the AI so be patient…;-)

  3. That must be it.

    I personally look forward to the day when I can bow in submission to our robot overlords. ;)

  4. Slightly off-topic I suppose, but what kind of work you meant when you mentioned “working on revising and updating our JavaScript documentation”? I considered the Core JS docs to be good relatively to many other things on MDC.

  5. Part of what we’re looking at doing is unifying the documentation so that instead of reading the core document, then the “new in version x” documents, you can read one documentation set that has features tagged based on which version of JavaScript they’re available in. This will make it easier to find exactly what you need, and will likely make it easier for developers who need to deal with backward-compatibility issues.

  6. We have that for 1.6 array extras at least… Don’t think much reorganization is required for this to work. But OK, I see your point.