Oct 292010

Somehow, the entire XUL Tutorial vanished from MDC sometime in the last three or four days. There’s no record of it having been deleted or moved, but it’s no longer there. It shows up in Google cache from October 25, so we know it happened sometime after then.

I have opened a ticket with MindTouch to see if they know of a reason this might happen, and if so if there’s a chance it can be recovered. Otherwise I will have to work with IT to look through backups and figure out what we need to do.

It’s possible fixing this may require rolling the site back, so you may want to hold off on large contributions until this is resolved. I will try to find a way to fix this without rolling back the entire site, but if it comes to that, we’ll lose changes.

I’ll post on dev-mdc and here, and of course on my Twitter account at @sheppy (which is always your go-to point for top-of-the-moment info) as I learn more.

I will be out and about dealing with getting my Toyota’s recall issue taken care of today, but will be watching this situation on my cell, and while I’m at the dealership waiting I will have my laptop out and be working from there.

 Posted by at 12:39 PM
Oct 272010

The MDN Doc Center (as the documentation part of the Mozilla Developer Network will be known going forward) is getting ready to receive a new look, which will help it match better with the rest of the MDN web site.

We’ve put a few iterations into the design, trying to maximize the amount of your browser window will contain the actual documentation you want to read, while still making the required user interface options available. I think the design team has done a good job here, and I’d like to share the look with you now.

A mockup of what MDC documentation pages will look like.

Key features of note here:

  • The header area at the top of the page is now vertically much smaller than it is currently (and vastly smaller than the rest of the MDN site). This maximizes screen real estate on modern widescreen displays — especially on netbooks.
  • The breadcrumbs bar has been moved more obviously up into the header, and is smaller than it currently is, making room for our increasingly hierarchical site layout.
  • The tags area at the bottom of the page is much prettier than in the current site, and should present a nicer interface for editing the tags than we have currently.
  • The drop-down menus for accessing page and site features have been moved into the main header area, alongside the breadcrumbs, again reducing the amount of space the header area takes up.

There are still some iterations to be done on nailing down final details, but the scripting work has largely been done for the first draft, and we hope to have a version of this skin staged on a test version of MDC soon, so people can give it a try and offer feedback. I’ll be sure to blog further as we close in on that!

 Posted by at 2:03 PM
Oct 222010

This week, work continues apace on Firefox 4 documentation, as well as some cleanup of how we do things on devmo. It was a good, productive week!

  • The documentation for JavaScript typed arrays is complete, or roughly so, pending feedback. More examples are sure to follow as documentation work on WebSockets and the final touches for the docs about File API gets done.
  • Wrote the new IFSummary template, and its child templates VersionTimeline and xverblob. Those have been blogged about separately.
  • Wrote documentation for the Web Console. This will need revising as there are some improvements coming in Firefox 4 beta 7 or beta 8.
  • Wrote about the new TabAttrModified event.
  • Wrote up notes about the removal of child HWNDs.
  • Talked to Jay and others about MDN design stuff.
  • Continuing to iterate on bugs related to the update of MDC to MindTouch 10.
  • Added a list of categories to the documentation for nsIScriptError; this includes information about which categories result in output into the Web Console. There are currently no details on what the categories mean. I may be adding that soon, depending on whether or not I get the energy to pore over the code and figure it out for the 10 people who actually care, worldwide. :)

I’m quite pleased by the progress of the Firefox 4 documentation now. There’s still lots to write about, but we’re doing a good job with the big stuff. There are a couple of big things left to write up. WebSockets and restartless extensions, in particular, but generally we’re in really good shape.

 Posted by at 4:59 PM
Oct 212010

I took a break the last couple of days from writing Firefox 4 documentation to put together some new templates to help improve the look and feel of our Interface Reference documentation. The one that’s exposed directly to you is the new IFSummary template, which replaces the old InterfaceStatus template that we used to use at the top of articles. The InterfaceStatus template now actually calls through to IFSummary, although it doesn’t take as many parameters so the results are suboptimal.

This creates a much better box at the top of the page presenting in a consistent format key information about the interface. For example:

There are tooltips displayed as you mouse over the version timeline indicating details; for example, the yellow dot (which is round in browsers supporting border-radius) indicates the version in which the interface last changed; mousing over the dot gives a tooltip with the exact version number.

Here’s a list of all the parameters the template accepts:

Path of the IDL file defining the interface
This is used to create a link to the interface’s IDL on MXR so the reader can refer to it if they wish.
Parent interface
This is the name of the interface upon which the interface being document is based. This will be turned into a link to that interface in the interface reference and displayed.
scriptable/not scriptable
A string indicating whether the interface is scriptable or not. You must use either “scriptable” or “not scriptable” (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.
Last changed in what Gecko version
This is a string indicating the version of Gecko in which the interface was last changed. Should be a string in standard Gecko version format, such as “1.9” or “1.9.2” or even “”.
Summary (optional)
A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus template (which now calls through to this one). You should always provide this.
Version introduced (optional)
If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline showing the availability of the interface in contrast to the history of Gecko, in graphical format.
Version deprecated (optional)
If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.
Version obsoleted (optional)
Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.

Under the hood, the VersionTimeline template generates the actual version timeline chart, and even further under the hood is the xverblob template, which takes a version number in the format w[.x[.y[.z]]] and constructs an integer value that can be used to compare two versions or do other math (such as taking a version, comparing to another version, and generating a percentage of one as compared to the other). This might be useful in other templates in the future.

Although I’m sure there will be changes to these templates over time, I’ve updated the custom templates documentation with this information as well as several examples, and the sample interface reference article page has likewise been updated. You should take a look!

 Posted by at 1:08 PM
Oct 142010

This week includes much doc sprint goodness!

  • Updated the CSS Transitions documentation per review feedback from dbaron:
  • The -moz-image-rect value for CSS backgrounds is now documented; this lets you use subrectangles of an image as backgrounds.
  • The Content Security Policy documentation is now complete and tech-reviewed.
  • Began cleanup work on Firefox 4 for developers, starting by turning the mishmash of bullets under the CSS section into a series of tidy tables.
  • We’ve got MindTouch 2010 installed on our staging environment. There are things that aren’t working right yet. I’ll be looking into those when I get home after the doc sprint.
  • -moz-calc() is now documented.
  • Created two new templates for use in building table-of-contents pages:
    • Template:TOCSectionForTag creates a table of all the articles that match two tags, filtering the output through another optional template to style the output.
    • Template:AlphabeticalTOCForTag creates a table of contents for all articles matching a given tag, filtering the output through an optional template to style the output. Each letter of the alphabet gets its own section.
  • Wrote an article that attempts to explain the concepts of inner and outer windows.

All in all, an excellent week for documentation!

 Posted by at 12:42 PM
Oct 102010

I spent today working on documentation for Content Security Policy. It’s not quite done yet, but I have written much of it. If someone would like to look it over, that would be fantastic, as that would let me get it finished up tomorrow.

I’ll be writing about CSP reports tomorrow.

If you’re not familiar with CSP, it’s a new technology that lets a site tell the browser from where content is allowed to be loaded. By using a known, carefully designed method for sharing information about legitimate domains from which to load content, the browser and server can work together to help mitigate a wide variety of attacks.

I’m not really a big security guy, but this is still pretty cool. You should look into it. The best part is that it gently falls back to working normally if either the web server or the browser doesn’t support CSP.

 Posted by at 11:16 AM
Oct 092010

This got published prematurely, but here’s what I have so far. The doc sprint is still underway, or this would be more impressive.

  • I’ve now documented the changes to how we handle DPI for CSS.
  • We have a basic introduction to SVG animation, and I’ve filed a bug to track writing complete SVG documentation (these docs are currently pathetic, and nobody really has any good ones).
  • The CSS function -moz-calc() is now documented.
  • Lots of little changes not worth specifically documenting.
 Posted by at 11:55 AM
Oct 042010

This week was not nearly as productive as I’d have preferred, for health reasons. Still, here are the things I did get done:

  • Finished the documentation for createHTMLDocument() and posted the code sample I wrote a while back, now that the bug that prevented the sample from working has been fixed.
  • Added documentation and an example for the canvas method mozGetAsFile().
  • Added a new DOMLiveSample template for creating a “live example” button for DOM Reference pages.
  • Finished the FormData documentation.
  • Updated our spammer ban-by-IP code, which is in the queue for IT to update to our staging server for testing.
  • Queued up requests with IT toward updating our staging server to MindTouch 2010 for testing, as we progress toward upgrading MDC to that release since our planned new wiki system is going to take longer than originally expected to develop and deploy.

This coming week (that is, the week of October 4th) I’ll be doing a little bit of doc work leading into the Open Web Doc Sprint we’ll be doing in Paris.

 Posted by at 2:16 PM