Aug 272010

Here, for your amusement/enjoyment/derision, is my log of the more noteworthy things I accomplished this week.

That’s a lot of miscellaneous stuff written up this week! On top of that, we rolled out the next phase of the big MDN upgrade this week (which admittedly I personally had very little to do with, other than some very minor fixes to the skin for the documentation wiki pages).

There are plenty of big things left to document, but even more little ones. My tentative plan for next week is to start by working on the new audio API documentation now that that’s landed.

 Posted by at 4:13 PM
Aug 202010

Here’s a list of the stuff I’ve done this week. This is a pretty raw dump, to help keep track of what I’m getting done, but you might find it vaguely interesting.

  • Animations using MozBeforePaint; this article provides how-to information, in concert with the reference documentation it links to, which I also wrote this week.
  • Wrote up the nsIDOMWindowUtils method nodesFromRect(). It’s currently the only method in this interface that’s properly documented, but it’s a start.
  • Updated nsIDocShell and nsIWebBrowser docs to mention a new attribute.
  • Documented the accelerated attribute added to XUL windows.
  • Documented -moz-element().
  • Documented the bottom and right attributes for the XUL stack element.
  • Updated more documentation related to XPCOM registration changes.
  • Documented the tabbrowser showOnlyTheseTabs() method.
  • Added an example to the docs for :-moz-window-inactive, and added it to the CSS Reference.
  • Updated Places reference documentation for changes to allow asynchronous monitoring of results. The conceptual how-to guide needs updating still.
  • Updated the MDC Copyrights page with clarified information on code sample copyrights; specifically, new code samples created henceforth are in the public domain.

I also did some work on the MDC skin, in preparation for the rollout of the next phase of the Mozilla Developer Network site, which is due to happen Real Soon Now.

 Posted by at 7:34 PM
Aug 122010

Obviously, Janet and I are heads-down working on Firefox 4 documentation these days. I thought today would be a good day to share a bit about what’s going on there.

Help us help you help others

First off, my traditional plea: if you’ve got code you’re working on that even might impact documentation, please add the “dev-doc-needed” keyword to the relevant bug or bugs. This will bring it to the attention of the writers. If there isn’t a relevant bug (or the relevant bug is extremely arcane), you can alternatively just add a blurb to the Firefox 4 for developers page or the New in JavaScript 1.8.5 page, as appropriate.

New and updated documentation

Now that that’s out of the way, let’s see what I’ve been up to, writing-wise. Having finally battled my way out of a crippling, multi-month writer’s block attack, material has finally started pouring out in quantity again in the last week or so.

  • The js-ctypes documentation is now finally complete. I’m not yet totally satisfied with the organization of the material, but it’s got all the facts in place now. I’ve requested a technical review of that documentation.
  • The buffered attribute on audio and video elements is now documented, as are the underlying XPCOM and DOM interfaces.
  • The DOM window.mozPaintCount property has been documented.
  • I’ve written up the X-FRAME-OPTIONS HTTP response header.
  • Added the new page Securing your site, which provides convenient links to articles about web site security.
  • Updated the documentation for the JavaScript Date object to indicate the new support for ISO 8601 dates.

That’s some real progress. Lots left to do, of course, but that’s always the case, right?

 Posted by at 2:31 PM
Aug 122010

Obviously search is busted on MDC right now, and has been for almost two weeks now. We’re tantalizingly close to having it fixed. This problem was caused by a combination of a minor glitch, compounded by a communication error, multiplied by my impatience, then polished off with a larger technical problem.

The story of what’s happened is, I think, an interesting one.

About two weeks ago, search abruptly stopped working, reporting an error along the lines of “The search query you entered contains characters which need to be escaped.”

We’d seen this error before, as a result of a strange communication issue with the database server. So I asked IT about it, and they said there didn’t seem to be a problem. Instead of being patient and waiting to see if the problem cleared up on its own, or to see if IT found a problem and fixed it, I decided to use the MindTouch control panel to rebuild our search index.

This… was not the right decision.

You see, the lucene-based indexing tool used by MindTouch is extremely resource-intensive, and pretty much uses every drop of the server’s capacity. And if there’s any load on the machine other than that, the indexer tends to abort abruptly. This would be the “larger technical problem” I previously referred to.

So the indexer deleted the current site index and started rebuilding it, only to fail. It was at about this time that IT let me know that they had found a minor problem (I don’t know what it was) that was probably responsible for the original search error.

But, by this point, the damage was done, and the MDC index was gone.

Since then, I’ve been working with IT and MindTouch to get the index rebuilt. We removed one of the three servers hosting MDC from the pool and ran the indexer on it to build the index, which did complete successfully. In theory, sometime today that index will get copied to the other two hosts, and then all three will be back online. I’m waiting for IT to get that done now.

After that, the index will need to be refreshed, but that will happen automatically and as a much smaller job than a full index rebuild, should go without a hitch (it has in the past).

 Posted by at 8:46 AM
Aug 092010

The new Add-ons Builder from Mozilla Labs has become a must-have tool for me when I’m writing documentation for Gecko and Firefox. In the past, when I needed to try things out before writing documentation for a new API, I would have to write up an extension, install it, debug it (with the repeated Firefox relaunches that entails), then finally write my documentation.

With the Add-ons Builder, I can write sample or test code in-browser, debug it in place without any restarts, and write my documentation — all at the same time. No more writing an entire extension to test two lines of code. I just drop them into the Add-ons Builder and go.

The amount of time this has saved is huge. Even better, my simplest code snippets are getting tested much more often. In the past, I rarely bothered to test one-liners, but now even those get a quick trial run.

So, a huge thumbs-up and thank you to everyone responsible for creating this tool. I’m your number one fan!

 Posted by at 3:10 PM