• Updated the HTML5 audio element doc for the new preload attribute, and updated the nsIDOMHTMLMediaElement documentation to match.
• Documented the new :valid, :invalid, :required, and :optional CSS pseudo-classes.
• Documented the document.mozSetImageElement() method.
• Updated docs for the JavaScript NaN, Infinity, and undefined global objects to note they’re now read only.
• Documented date.toJSON().
• Documented the new tabbrowser.getIcon() method, and, while I was at it, the previously undocumented tabbrowser.setIcon() method.
• Documented the aysncClose() method, and added a bit about closing database connections.
• Documented the tabs.tabbox XUL property.
• Documented HTTPS Strict Transport Security.
• Fixed documentation of related to bug 11011 by cleaning up the :-moz-broken documentation and adding docs for :-moz-user-disabled and :-moz-suppressed. These are old Firefox 3 (Gecko 1.9) items that were mis-documented due to a communication snafu.
• Documented :-moz-placeholder.
• Documented :-moz-loading.
• Documented :-moz-handler-blocked, :-moz-handler-crashed, and :-moz-handler-disabled.
• Documented the new drawintitlebar XUL attribute.
• Updated a number of pages with minor notes not worth mentioning specifically.
• Cleaned up a bunch of pages.
• Copy-editing!

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.

• 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.

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?

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).

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!

Take a look at the release notes.

Given that we’re planning to switch to a new wiki system in the first or second quarter of 2011, I’d like to get your opinions on whether or not we should install a major software update like this one right now.

On the plus side, it does give us some nice new features and usability improvements both for editing and maintaining, as well as supposedly substantial search improvements.

On the minus side, we’ve had problems with major MindTouch upgrades in the past. In addition, some of the exciting new features are ones that we won’t have with the first version of the new MDN wiki system our development team is building for us. I’d hate for people to get used to new features only to have them go away a few months later.

So what do you all think? I could go either way on this one — I’d like to have the new features but worry about how it would impact the community. So let me know how you feel either by email or commenting here.

In general, performance is better than it was a few weeks ago. We do see occasional lag, sometimes worse than others, but the site is definitely working better than it was. Work is ongoing to improve things further.

Among other things, we’re testing enabling a memcache server for caching query results, which would let us cache query results across requests, further improving performance. I don’t know when this testing will be completed.

Looking even farther into the future, MindTouch’s upcoming Olympic release has a bunch of improvements that will hopefully benefit us. This update is due later this summer, and includes:

• CKEditor 3 is the default editor; this editor is faster and will have a much improved toolbar.
• Users will be able to rate content thumbs-up or thumbs-down; this will help make quality content float to the top, and alert writers to material that needs work.
• The article tagging interface will be more efficient.
• User pages will be “dashboards” with mini-apps, notepad space, and user activity reports.
• A new “page layout wizard” will be available; we’ll be able to create page templates that users can choose among to pre-layout content. For example, when documenting an interface, you can get a page with the basic hierarchy of the page, including the default tables for attributes, constants, and methods, already in place.
• Improved search, with smarter page ranking, various search result sort options, and more.
• Improved “curation” features, to help identify potentially out-of-date content.

Should be a nice update. We’ll keep an eye on it.

Stability

We’re definitely more stable than we were, although we are still having occasional errors. We don’t yet know why, but I’m looking into that and will post again once there’s something to report.

RSS feeds

MindTouch has implemented some new caching support for RSS feeds that they’ve given us a patch for, which we’ll be installing soon. At the same time, we’ll be upgrading to MindTouch 9.12.3, which is apparently arriving shortly. We’re actually already using most of the fixes in that update (there’s only one that we don’t already have).

Caching

We also plan, sometime next week, to bump the caching currently in use from “request caching”, which only helps a little bit, to using memcache to cache more usefully. This will also let all our hosts share cached data, instead of each maintaining their own cache.

All of these changes are going to be tested and staged before being deployed, so I don’t have exact dates yet on which you’ll see them take effect.

Performance status

Performance is better than it has been in some time, although it’s clearly got more room for improvement. We’re still chasing stuff related to the RSS feeds right now, but once that’s done, we’ll do another round of profiling to see if we can figure out where we stand.

Hopefully we’ll be able to start re-enabling some of the feeds we’ve shut off after that.

One thing we did already this week is fix an error in our robots.txt file; all spiders were being told to ignore the entire site, instead of just the areas we wanted them to ignore. This hopefully won’t negatively impact performance (it certainly won’t improve it), but should get our search results on Google and the like back up to date.

A few articles have already been written. There’s lots left to do, of course, but we’re making progress. If you see something you’d like to write about, feel free to contribute!

As always, the content of that page is in flux while the feature set of Firefox 4 continues to be adjusted. In addition, it’s obviously too early to be sure exactly what articles will be produced for all the topics at hand, so there are a number of placeholders.

If you’ve contributed code to Gecko or Firefox recently, you may be hearing from me or one of the documentation contributors soon, to gather information about your area of expertise as documentation comes together.

Even though feeds were being cached, and only refreshed on demand, spiders and bots were causing “on demand” to mean “every time they expired”. And since every page on the site has multiple feeds, and every user has a feed of their contributions, something like 360,000 feeds were being queued for regeneration, meaning that there were pretty much always feeds being regenerated, chewing up lots of CPU.

Now, instead of each host constantly having something like 25+ tasks ongoing, never less, each host is averaging more like 3 ongoing tasks at any given time, because they’re not piling up while the system is busy handling RSS feed generation.

Work is ongoing on coming up with a fix for the performance of the feed generation code, so that the other feeds can be re-enabled, but at least we have the main one still.

In the meantime, performance seems quite reasonable. Please let me know if you run into any performance issues, so I can get them looked into.