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