Burning Chrome

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.

IRC summary of #documentation

Per bernd's comment a few days ago, I had a little chat with fantasai about potential "Doc Days" and the overall documentation effort. I have a rough summary (posted in extended entry) of what we talked about, courtesy of fantasai. We'll be seeing a blog later from fantasai about this in some more detail.

fantasai: WeirdAl posts blog entry about Doc Days
fantasai: http://weblogs.mozillazine.org/weirdal/archives/006711.html
fantasai: fantasai notes concerns with not having a good idea of what documentation needs to be written
fantasai: and therefore not a good idea of how it should be organized
WeirdAl: (roadmap bug)
fantasai: fantasai filed bug against Bugzilla for a READY state
fantasai: which Hixie requests for handling regular bugs
fantasai: (state represents bug ready to be tackled - specs, testcases, description, etc. all good)
WeirdAl: checkins? :)
fantasai: would be useful for docs as well - this request has enough info that random person wanting to help will know what to do
fantasai: another problem with doc bug triage:
fantasai: no flag to distinguish
fantasai: - fix minor errors
fantasai: - major rehaul
fantasai: - write new doc
fantasai: different kinds of bugs
fantasai: people searching for one often don't want to look at unfiltered list including others
fantasai: WeirdAl considers documentation-specific issue tracker
fantasai: fantasai suggests that Bugzilla+wiki+doctor would probably be sufficient
fantasai: and has less overhead
WeirdAl: weirdal agrees
fantasai: fantasai notes:
fantasai: I don't believe that [mozilla.org] docs should be hosted on a wiki
fantasai: but I think that it's a great place to work on them
fantasai: start an article
fantasai: and multiple people can work on it at the same time
fantasai: it's easy to do, anyone can help, make small/large changes, poke it around
fantasai: and not worry about it being scrappy or disorganized at first
fantasai: -- like a public workspace
fantasai: CVS checkin is like publishing
fantasai: current workarounds are a) use your own webspace b) use bugzilla attachments c) checkin to mozilla.org prematurely
fantasai: none is good :)
nilson: So you were proposing to use kb.mz.o?
fantasai: weirdal looks around web, notes existance of www.naturaldocs.org
fantasai: yes
fantasai: points out that auto-generated docs don't handle XUL etc
WeirdAl: (I should note that my thinking at the time was on the level of source-code docs)
fantasai: -
fantasai: Doctor is great for handling "minor errors" category of problems
fantasai: "rehaul of existing docs" and "write new doc" should ignore diffing
fantasai: would be useful to have wiki for document development
fantasai: we look at kb
fantasai: wrt wiki, would need (besides standard editing of articles)
fantasai: a) linking wiki article to bug report (URL field of bugzilla?)
fantasai: b) redirecting to completed document once its done
fantasai: so can move doc from wiki to moz.org
fantasai: but not break links that decide in-progress doc is better than none
fantasai: c) wiki needs to allow direct editing of markup
fantasai: -
fantasai: wrt bug triage, need to categorize by skillset
fantasai: someone looking for something to work on may know XUL but not C++
fantasai: so being able to restrict search to bugs that don't require C++ would be good
fantasai: someone knowing Perl might want to restrict search to bugs that /do/ require Perl
fantasai: etc.
fantasai: applies for documentation too
fantasai: weirdal notes that the tree components for docs in bugzilla are mostly useless
fantasai: consider various reorganizations, nothing conclusive
fantasai: fantasai pulls up kb summary of mozilla products
fantasai: http://kb.mozillazine.org/index.phtml?title=Intro_:_Summary
fantasai: points out that there is lots of useful info there
fantasai: but it's targetted at people interested in mozilla project
fantasai: not downloaders
fantasai: whereas mozilla.org's products page is exact opposite

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 mozilla.org 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 books.mozdev.org 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.

Mug shot from San Diego, last June