Apr 302013

Last night, I got home after another fun and productive MDN documentation sprint; this one was held in Mozilla’s lovely Vancouver office. In addition to Mozilla’s paid writing staff and a few core contributors, we had Mounir Lamouri, a Mozilla platform engineer, on hand to offer technical expertise about web-based device APIs. In addition, two Vancouver-area residents, Aras and Amr, also joined us, making their first contributions to MDN!

The MDN doc sprint team in Vancouver in April 2013.

Photo provided by Florian Scholz.


To top it all off, Vancouver-based content strategy expert Rahel Bailie dropped in to help us do a quick-and-dirty content strategy analysis; it was reassuring to discover that we’re more or less thinking along the right lines and on the right track in that regard.

Both virtual and in-person sprints have their pros and cons. Virtual sprints let people participate from anywhere without the need to travel and leave their normal lives and families behind. But in-person sprints give us the opportunity to have the kinds of conversations that work best when everyone’s in the same room together with a whiteboard. We had several of those conversations during this sprint in addition to documentation writing activities.


Some of the whiteboard discussions we had during this sprint included:

  • We talked about the content and structure for the home page and global navigation of MDN. Expect to see these changes start to happen in the next few weeks!
  • A team met a couple of times to draft and refine a specification for the Localization Dashboard. This has been proposed as a Google Summer of Code project. Whether a student tackles this for GSoC or our own dev team builds it, having a spec is an important step.
  • We had a very long and engaging discussion about MDN’s page types and the elements they need. I will be turning our sketches and notes into a specification proposal this week.
  • We brainstormed ways to improve our involvement in events, whether they’re MDN doc sprints, other Mozilla events, or even external events.
  • We talked about our new process for managing documentation bugs by using the “Developer Documentation” component in Bugzilla along with Scrumbu.gs.

Documentation written

We also had lots of documentation written. I doubt this is an exhaustive list (in fact, I know that it isn’t), but it’s a list of what people specifically noted down that they worked on. Even as an incomplete list, this is a lot of great work. I’d like to thank everyone for their time and effort!

Aras Balali Moghaddam

Aras modified the following pages to make use of live code samples. We’re pretty excited about our live sample system, so getting more of them is always awesome!

Florian Scholz

  • Updated the MathML mspace element’s documentation per bug 717546.
  • Updated the methods of inlDOMUtils per bug 839443.
  • Updated the documentation for document.createElement() for bugs 851916 and 844127.
  • Updated the documentation for table.insertRow() and tableRow.insertCell() for bug 824116.
  • Created documentation based on several code bugs marked dev-doc-needed.
  • Updated MathML compatibility information on reference pages to note that Chrome has completely removed MathML support.
  • Moved MathML pages into the new hierarchy (Web/MathML and Mozilla/MathML_Project).

Eric Shepherd

  • Added a section about media presentation to Firefox OS apps tips and techniques.
  • Updated the docs for nsINavHistoryService to fix bug 703893.
  • Updated the docs for JS_SetGCZeal to note a signature change in Firefox 14, per bug 787723.
  • Created the template APIListAlpha for producing alphabetical lists of subpages as pretty indexes.
  • Started work on building the hierarchy for the new open Web documentation structure, including the Web landing page and the Web APIs page.
 Posted by at 2:18 PM
Apr 252013

Ah, spring! The flowers bloom, the snows melt (usually), and lovers of the Web and of Mozilla are heading to Vancouver, British Columbia to participate in our spring documentation sprint at the Vancouver Mozilla Space.

We’ll be gathering writers and a few developers together to pound out as much great documentation as we can, along with, I’m sure, a few fun evening activities.

If you can join us, feel free to drop in! Or participate virtually by logging into MDN and joining the chat in the #devmo IRC channel. We’ll save a seat for you at the ol’ keyboard.

 Posted by at 8:13 AM
Apr 082013

There’s been a great deal going on on the Kuma front of late. If you’re not already aware, Kuma is the Mozilla-built wiki platform that powers the Mozilla Developer Network (MDN) documentation. Today, I’m going to share a few tidbits about what the team is up to and what’s coming in the near future.

New Features

We have some new features! Let’s take a look!

  • You can now specify a maximum depth for tables of contents on individual pages. Say you have a page that has lots of repetitive sub-headings. You can keep those from exploding the length of the TOC now. Just open the “Edit Page Title and Properties” pane in the page’s editor, and you can now specify how deep the TOC should be allowed to get (or disable it entirely, as before).
  • You can now add a revision comment when saving new articles; this can be especially useful for people like me to note things like “just getting started, more to come,” for example.
  • Admins now have a “View in Admin Panel” option to look at a page in the Django admin panel; this gives us access to the option to delete a page, for example, saving precious time and hair-tearing-out.
  • Unused bits of data are no longer displayed in revision diffs and page history. We used to show some information that we inherited from SUMO but don’t actually use.
  • The page footer now includes a link users can follow if they’d like to contribute to the Kuma project.

Back-end Improvements

We’ve also done more work on improvements to the internals, structure, and so forth. This includes work on upcoming new features that aren’t exposed to users yet. Some of the more interesting ones:

  • Upgraded to Django 1.4.5.
  • Upgraded to jQuery 1.9.1.
  • The CSS for our custom fonts has been updated to allow the fonts to be cached locally instead of having to be re-downloaded all the time.
  • A number of bits of optimization work have been done to help improve page load times and the like.

Bugs Fixed

  • You can now use the title attribute on <div> blocks.
  • Several other minor bugs have been fixed.

As you can see, the team has been busy. Now that the bulk of the back-end work on the Elastic Search and Django upgrades has been finished, the team is moving on to other things (although the front-end work on ES is still ongoing). I hope to see some really good new stuff arrive soon.

Coming Soon

Work has begun on designing and hopefully soon implementing the notification system that will be used by our review queue as well as by page watchlists. Once we have that system, a lot of awesome new features will become possible, and we’re really excited to have that work underway!

Also, section editing is gradually making progress. I hope we’re in the home stretch on finally being able to edit individual sections instead of having to edit the entire page every time we want to make a simple tweak.

The guys are working hard, and I’m very proud to work with them! Thanks guys!

 Posted by at 11:14 AM  Tagged with:
Apr 052013

We have a lot going on these days! Obviously, Firefox continues to surge forward, with new features all the time. That alone would keep us busy, and indeed it does. Jean-Yves Perrier has been heading up Firefox developer documentation work for the last couple of months, and I expect he’ll keep doing so for the foreseeable future.

Of course, there’s more than just Firefox. The developer tools team has been cranking out amazing new tools to help Web developers (and, in turn, Firefox OS developers), and those need lots of documentation work. Will Bamberg has taken over that work from me, since I’ve been completely swamped lately. This fits in well with the work he’s already been doing with the Jetpack documentation, since many of the same people are involved.

Mark Giffin, working under contract (although he’s been working with us so long, it’s hard to think of it that way!), has been working hard on the open Web apps documentation. This documentation obviously plays a key role in our plans for Firefox OS, and it’s great to have him pounding away at that.

Janet Swisher has been so busy for so long being “distracted” away from writing by her work organizing doc sprints and other community activities that it’s in the process of becoming official; she will become our MDN community manager (although I’m not sure precisely what title is involved). She’ll be working full-time on building our developer community and helping to organize events. This is going to be fantastic to have someone doing that for real, and I know Janet will continue to do it well — especially once it’s her “real” job!

In the meantime, I’ve been sliding more and more into organization work. There are two kinds of organization involved.

Content organization. I’ve been working, gradually, on rearranging content on MDN to be more logically structured. The Web apps documentation has been rearranged, as has much of the WebAPI documentation. In addition, I have cleaned up the structure of the Firefox OS content as well. This work will continue for some time, but it’s a relief to finally be making some amount of headway. We have big plans for rearranging the so-called “DOM Reference”. For details, you can see the article Web platform documentation hierarchy.

Team organization. As the MDN docs team has grown — both in terms of paid staff and in terms of our awesome army of volunteers — it’s become more difficult to keep up with what’s going on. This is, of course, exacerbated by the fact that we have so many projects to work on. So going forward, more of my time is going to be spent organizing and coordinating the writing team. I’ve been doing a lot of writing about documentation processes, and gradually we’re nailing down plans for ways to improve how we do things.

One thing you should expect to see soon is pages you can visit to see what each team member is currently working on, as well as a list of upcoming documentation projects and their status.

I’ll be blogging more soon specifically about the organizational work we’re doing, once the actual plan documents are finished and posted onto MDN.

In addition to organization, I’ve been working on the MDN Style and User Guide documents. These suites of documents will help us bring new contributors into the fold, and will help us produce better, more consistent documentation in the future. On top of all that, the style guide is going to be used to help inform the design team as they work on designing the next generation UX for the MDN web site. The new design is going to be spectacular, but only if we participate in the process.

I’ll blog more about this once these documents are farther along; however, one thing you can look at and help with right now is the MDN page types list. This article is meant to list all the basic kinds of pages we have on MDN, and to list the features each needs to offer. Eventually this will be detailing each type of page all the way down to which visual styles are needed in order to construct them, so that the design team knows what CSS we will need. This information will also be used to help us build better toolbars and to improve the editing experience in general, so if you have frustrations with editing on MDN, this page is a place you should go and contribute to!

So that’s what we’re up to, in brief.

 Posted by at 12:46 PM