Bit Stampede

The last week or so, I’ve been working on sample code for the Source Editor API. While this API is not incredibly mission critical, in that it doesn’t directly affect web developers, and isn’t in the critical path for documentation, I’ve enjoyed this work, and the time spent writing about it — and, more importantly, building sample code for it — has been educational.

One thing that occurred to me is this: we need more real-world examples of how to do things. Too many of our examples are simple, fictionalized snippets of code that don’t show you how to do things in the greater scheme of getting things done. However, you still need to document things in context, too.

What I propose is this: what if we set up a section on MDN for larger examples of all kinds, where each page is a complete example, with downloadable code and one section for each method or interesting section of the example, talking about how it works? Then we can link to those sections from the relevant documentation site-wide.

For instance, this example I’m working on shows how to do all of the following things:

• Create a new XUL window
• Import several JavaScript code modules
• Add a Source Editor to the window
• Interact with the Source Editor
• Create and manage a menu bar
• Check and uncheck menu items given the state of the source editor
• Update the display in a status area of the window given information obtained from the source editor
• Asynchronously fetch the contents of a page using NetUtil
• Overlay XUL from within the browser into the source editor to re-use UI and code
• Save the text from the source editor to a local file on disk
• Display alerts using the prompt service
• Call various methods from XUL definitions of UI
• Add and remove event listeners
• Some parsing of file and pathnames
• Set the title of a window based on the name of the item being edited
• Add an item to the browser’s content area context menu under specific conditions

That’s a lot of stuff, and being able to demonstrate how all of those things are done in a real-world extension has a lot of value. By having a page that covers all of the things this add-on does, then being able to link to the appropriate parts of that page from all over the site, we can really bring our documentation to a whole new level.

Any thoughts?

As pretty much everyone knows, our documentation for events (both standard DOM events and Gecko-specific ones) is pretty lame. We’re missing a lot of stuff, and what we have is often bad and poorly organized.

We have a new event reference page:

https://developer.mozilla.org/en/Mozilla_event_reference

Which embeds the Gecko and DOM event references:

https://developer.mozilla.org/en/Gecko-Specific_DOM_Events
https://developer.mozilla.org/en/DOM/DOM_event_reference

However, neither of these pages are complete, and most of the events have little or no documentation.

This is obviously important documentation, but has never managed to drift to the top of the to-do lists of any of the writers.

For that reason, we’re now looking for a contractor that we’d pay to write and clean up this material. The goal is to have complete documentation of all standard events for the DOM and other open web APIs, as well as for Gecko-specific and internal events.

This will probably take a while, although at the moment I don’t know how long. There’s quite a lot to be done; it would involve, among other things, going through the spec to find events and document them, plus going through the code to see which ones we support and which ones we don’t (as well as, hopefully, where our implementation deviates from spec).

Additionally, the writer would need to be able to look through the code to find, understand, and document the Gecko-internal events, most of which are currently entirely undocumented.

If you’re interested, or know someone that might be interested, please let me know!