Nov 092007

One thing that’s interesting about writing developer documentation is that it’s totally possible to write about something you don’t understand at all.  I’ve done this in the past; I once wrote a 450-page “chapter” that was widely received as being quite good even though I literally couldn’t actually figure out how to write code to do the things it was explaining how to do.  No exaggeration.

This amuses me.

I think that means that expectations of documentation are often rather low.  Documentation is obviously much better if the writer actually understands the material.  This is why I prefer to be able to write about things that I have the time to write sample code for.  Not just because sample code is useful (you can often crib sample code out of the product itself), but because the best way to learn how to do something is to do it yourself.

My best documentation always revolves around stuff I actually had time to write code for.  This is pretty much a universal rule.

The trick is that some things it’s really hard to write code for.  Things that are really deeply internal to Firefox do not necessarily lend themselves well to writing code to try out, for example.


I’m actively working on the documentation for the Microformats API; you can see the work in progress, which is rooted in the article “Using microformats.”  This stuff is still in draft form, and a work in progress, so be gentle.

I’m finding microformats to be a more interesting topic than I’d expected, even though it’s a little harder to document than I’d expected.  I’m going to need to write some code to be more sure of myself in terms of how they work.   The problem is that I’m not exactly sure how really to do this.  I need to write a microformat handler, but I don’t know enough about how microformats work on the Web to actually do it yet.  I probably need to find a microformat that’s defined already but not implemented by Firefox and write code for it as an experiment; if anyone has a suggestion, please let me know.  The simpler the microformat, the better!


Places already has a lot of conceptual documentation, courtesy of the engineers who actually did quite a good job of writing it up (woohoo).  I’ve asked a student at Seneca to work on putting together initial reference documentation for it; hopefully that work will start in the next few days.

I’ll also need to write an example or two for Places.  There are a lot of very interesting things you can do with Places’ API.  This will actually likely be a fun example set to write — I just need to find and/or make the time.

Firefox 3 Beta

We’re almost to the beta; last I heard, it’s scheduled to roll in mid-November.  The vast majority of the substantial documentation work to be done for Firefox 3 will be done by beta, although not all of it.  I’m  pleased with that.  If over the next week or two we can get Places reference material in place as well as a little more work on the microformats API documentation, I’ll be quite satisfied with the place Firefox 3 documentation is in, despite the relatively short list of things that aren’t done yet.

We’re on a great path to have complete Firefox 3 developer documentation in time for the final release.  Something that would really help make sure we get there is if the subject matter experts on the various topics related to Firefox could do a quick search on the dev-doc-needed keyword and make sure that the bugs that crop up that are related to their areas of interest have a comment in them that makes it clear what needs to be documented.  Many of these bugs are tagged as requiring documentation changes but don’t make it clear at all what needs to be done.  By adding a quick note explaining what needs to be written up, you can turn what could be an all-day or multi-day research project into a quick document edit.

 Posted by at 12:26 PM

  One Response to “Microformats and Places”

  1. You could find a large number of microformats ready for the writing by looking at a Linux distribution’s package management pages. For example: – list the versions in stable, testing, and unstable. – give bug status. – summarize number of bugs open, closed, or with patches. – go nuts.

This site uses Akismet to reduce spam. Learn how your comment data is processed.