Mar 162012

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?

 Posted by at 7:30 AM

  2 Responses to “Integrating real-world samples with documentation”

  1. we need more real-world examples of how to do things I agree. I think *all* MDN examples should be excerpts of complete working programs. But “downloading” samples is so last century, instead (where possible) you should be able to open up the fragment to view/run/edit the entire working sample, jsFiddle style. For bonus points samples should all be in a suite that gets tested, and CSS Linted/JSHinted.

    I said this in 2010 on Jay Patel’s MDN Roadmap for 2010 post, he replied “couldn’t agree with [me] more”. But Mozilla’s push for a hackable read-write web seems external to MDN.

    Besides a jsFiddle-ish sample code runner (here it is done in 1kB!), the enabling MDN technology is some kind of excerpt template or tag that excerpts lines of code from a code URL; maybe that’s what you mean by “link to the appropriate parts of that page”. Perhaps this excerpt tag/template could use xlink syntax, maybe better if the sample code had explicit BEGIN{END}_EXCERPT “XUL definitions 1” comments in it that identify which lines appear in MDN samples. The problem comes when the code example changes, do you automatically regenerate the snippets and risk borking documentation pages? You need a “what links here” feature to see what MDN pages are affected by changes to the sample code.

    It’s a hard problem, but snippets from working programs you can interact with is teh awesomeness.

  2. Yes, having good jsFiddle integration on MDN is one of the goals for our impending site update.