May 132008

It was almost exactly a year ago that I wrote the first draft of the Firefox 3 documentation plan.  That marked the beginning of the effort to document the immense new feature-set of Firefox 3 from a developer’s point of view.

I thought it would be interesting to turn back the clock and take a look at how the Firefox 3 developer documentation was built.

Early scheduling

Ironically, on May 29th, 2007, I made my first prediction that the documentation for Places and the “updated Password Manager,” which wound up being the new Login Manager, would be among the first things documented.  This is particularly ironic since right now I’m actively working on finishing the documentation for Places — so instead of being the first thing written about, it’s going to be the last.

On the other hand, the Login Manager documentation was roughed-out by June 14, 2007.  There was still a little work to be done, but it was a start.

Stirring up trouble

By August 6th, Mark Finkle had posted initial documentation for FUEL, and most of the interfaces used by Places had initial reference documentation written.  Then, on September 18th, I posted my first “Hey, I think we’re almost done with the documentation, what do you think?” message.

This had precisely the desired effect: tons of email flowed in pointing out things that had yet to be documented.  Many of those things were things I’d never heard of.

On August 28th, I completed the documentation for the Download Manager, and was hard at work on a sample extension that would show off how to use it.  This was the first of the many things I’d never heard of previously.

For the next few months, it became a matter of plowing through the bug lists knocking off the smaller but sometimes more intricate issues that needed to be addressed in the docs.  Among these issues were a few key gems, though, including Microformats and continued work on Places.

Wrapping it up

Early 2008 started with a series of reminders that if there were issues not yet documented, to please file a bug against the docs to make sure I knew about it.  This is a critical step, because I often don’t know about all the things that are being done.  Indeed, this would become an issue in the spring of 2008, which we’ll get to shortly.

In mid-February, Mark Finkle posted a great article explaining how to create a web-based protocol handler, and a few weeks later, Sylvain Pasche contributed a similarly great article explaining how to create a custom Login Manager storage module (which will come in handy for whoever decides to implement Keychain support on Mac OS X).

The pleas for reminders about stuff that needed documenting still hadn’t let up, with another request going out on March 27th.  And the very next day, I followed up with a post mentioning a few things I was aware of that needed to be documented.

Those were all taken care of within the next couple of weeks, with the nsIJSON documentation landing on March 28th.  Amusingly, the caveat on that blog post still stands.  I’m still waiting for word on whether or not those two parameters will be (or have been) removed.  I need to remember to follow up on that.

A few days later, I posted documentation added for offline caching (on April 1)

Amusingly, that list also included alternative style sheets, which it turned out was not new in Firefox 3.  However, I still went ahead and wrote an article (including an example) to cover that topic.  The Thread Manager sample code and how-to came along next.

Amusing announcements

I announced about five times that the documentation for Firefox 3 was done.  The first time was way back in September of 2007, and the most recent was in March of 2008.  There’s still a little work to be done, but it’s pretty close!

Helpful helpers

A lot of people contributed to the documentation for Firefox 3.  Several students at Seneca pitched in, doing a lot of the initial passes at reference documentation for things including Places.  So thanks to AJ, Kenneth, and Andrew.

Several folks in Evangelism pitched in bits here and there, including Mark Finkle and John Resig. Rob Sayre also was very helpful, writing initial documentation for Microformats and a few other topics, which saved me a lot of research time.

Likewise, Dietrich Ayala wrote much of the initial documentation for Places, which, while a lot of it has been heavily overhauled or even removed since then, really helped me understand the concepts well enough to get the documentation whipped into shape.

Lots of others helped out too, and far too many to name.  Anyone who laid a finger on their keyboards while editing the docs in the past year contributed in some way to the Firefox 3 documentation being, without a doubt, our best set of developer documentation to date.  My hat would be off to you all — if I wore a hat.

Thank you!

 Posted by at 4:50 PM