Category Archives: Documentation

XPCOM Stream Guide: Help Wanted

I’ve just started putting together a guide on XPCOM streams over at MDN.  We already have wonderful guides on strings, hashtables, and arrays.  Streams are also really important, but there’s not much documentation on them.  So I figured, why not start some?

I’m going to be working with streams a bit over the next few weeks as I convert from SAXXMLReader.parseFromString() to SAXXMLReader.parseAsync().  Apparently, the parseFromString() method is not very nice.  So I’m dusting off some old tools and ideas, and I’ll be writing down what I run into that I think others can use.

The XPCOM Stream Guide is right now little more than an outline.  My own time is very limited; if anyone else wants to fill in some of the blanks, I’d really appreciate it!


First Doc Day: Results

  • I looked at the bug list; it looks like most of the bugs are trivial to fix.
  • I found two bugs that didn’t belong in docs; I moved one to Browser, where it was quickly invalidated. The other I think I didn’t move yet.
  • One of these trivial bugs to fix mcsmurf did post a patch; we asked Asa Dotzler and Tracy Walker to review.
  • The San Francisco 49ers were defeated by the Seattle Seahawks.

In other words, not much. Still, I’m happy with the results.
This is more traction we’ve gotten on documentation than we have had in a long while. I didn’t have any real goals for today, so any accomplishments are a good thing.
I’d say 30-50% of the bugs in Docs are filed against Mozilla’s XUL Reference. If the pages are frozen (due to a printed version being published), then we just need an errata page. If they’re not frozen, we can use Doctor to create patches. Either way, we can fix a huge number of bugs with just one volunteer taking the time to go through and make patches. I mean it: one person spending three or four hours can cut our bug count by a third, I think.
I did have two targets which no one volunteered for. In a sense, I’m not too disappointed, because these targets I plan on doing anyway.
That’s all I’ve got. Go Seahawks.

How about we make Sunday “Doc Day”?

… and on the seventh day, God rested. So do most of our developers, for very good reasons. Sunday is usually the lowest traffic day of any day in any IRC channel.
But we still get people in the channels asking for help. Less, certainly, but not zero.
I’m thinking Sundays would be great days to have a “Doc Day”, where we just go through the source code and the docs on and see what we can turn up that needs fixing and/or writing down. The various trees are usually very stable on the weekend, with few checkins.
So what would a Doc Day entail?
At first, not very much! When I tried kickstarting documentation a couple years ago, I fell flat on my face, mainly because I tried too hard to guide everything in a certain direction and we didn’t have enough feedback. We might still not get enough feedback on Sunday, but this time around I can afford to linger for 12 hours at a time online.
Probably we’d start out mainly by picking an area that someone wants doc’d, and we’d spend a day on it, gathering notes. Somewhere late in the evening Pacific time (say, 5 pm), we’d probably call it quits on note-taking and gather around one place to start compiling what we learned into a document or two.
I’d host it on my blog (thanks to my saveAsFile.js script), and we’d gather in a channel like #mozillazine to nitpick it and polish it to a submittable draft. The goal would be one major document (an article, an interface’s implementation, etc.) a week. Then, I’d probably ship off the draft to Asa or someone else who cares, and we’d get it posted.
One document a week. I think it’s doable. Who’s willing to help?
UPDATE: But not this Sunday. This Sunday, two of the hottest teams in football this year are going head-to-head. One of them happens to be that of my hometown, beaten only once this year. The other is the defending Super Bowl champions, unbeaten for nearly 20 games.
I’m beginning to think that I’m the Rodney Dangerfield of Mozilla development. I get a lot of things wrong, and that’s why I don’t get no… 🙂

Creating Apps: Hmmmm…

With the commencement of my new job last week (okay, it’s OfficeMax, part-time at $7/hr, but it’s something), I decided I could finally afford to buy Ian Oeschger & Co.’s book, “Creating Applications with Mozilla”. I’d read sample pages from several times, but having a book you can hold in your hand is very different from reading the sample pages online.
One thing the book doesn’t cover (probably because it never occured to anyone that it would be necessary) is how to install an XPI from a command-line prompt. This matters because it’s not clear how my poor Nvu 0.2, which wasn’t really designed to browse the web, will install Abacus without hacking installed-chrome.txt (not every Nvu user will want to play with that file). The appropriate web-based installation instructions can be found in Chapter 6, Section 3.