Jan 312013

As part of our effort to improve our documentation process, we now have a Bugzilla form that makes it easy to provide the proper information we need in order to handle a request for documentation. In addition to offering guidance as to how to fill out the form, fields that we don’t need (or need to have specific values) aren’t presented, and are handled automatically on your behalf.

If you find yourself often requesting the addition of (or changes to) documentation on MDN, you should seriously bookmark the new form:


The new form looks like this:

Screen shot of the new documentation request form

The Request Type indicates whether you’re asking for new documentation or a correction to existing materials. The Topic drop-down menu offers a list of topic areas (DOM, HTML, JavaScript, etc.) to help categorize your request. It’s helpful to specify a technical contact; this is the email address of someone that knows about the topic so that the writers can find someone quickly to help answer questions. This field supports lookups from Bugzilla’s user database, to help you get it right the first time.

The Development Bug field lets you enter the bug number of a bug that should be blocked by this documentation request. That lets us monitor the development process as well as to locate people that may know more about the topic to be documented.

The Urgency field lets you indicate how quickly the documentation request would preferably be handled. The default is “No Rush,” but there are options to indicate that the docs are tied to a given stage on the release train, as well as an “Immediately” option for emergency documentation updates.

It’s important to note that we make no guarantees as to how quickly documentation will be written. There’s a lot to write, and there aren’t that many people to do the writing, so sometimes even important things will sit around and wait for a while.

 Posted by at 7:00 AM
Jan 302013

If you’re a member of any of our illustrious localization and translation teams for MDN, you’ve likely noticed that for a while now, trying to save changes to pages that have been moved has been failing with a strange error about not being allowed to change the page slug.

This bug has just now been fixed, and you should be able to edit these pages again without any problems. Let us know if you’re still having problems!

 Posted by at 3:57 PM
Jan 232013

This post is not just a note about the changes in yesterday’s Kuma push to the MDN web site, but also serves to explain a change to our deployment process. The MDN development team is switching to a “continuous deployment” model, where new changes will be pushed to production as soon as they’re ready, instead of batching them.

Because of that, I won’t be blogging every single push anymore. Instead, I’ll mention specific new features as they’re ready for you to use, if they’re of major interest, or I’ll batch pushes together and mention the little but still interesting things all at once.

However, we do have a few interesting things in this new push, so I’ll mention those today:

  • The object returned by the wiki.getPage() KumaScript function now includes a translations array of objects that describe each translated version of the page. Each object in the array has three values:
    • locale — the locale of the translation
    • title — the translation’s page title
    • url — the URL of the translated page
  • The “revert this page” confirmation now shows the tag changes that will result from the reversion.
  • The “needs technical review” and “needs editorial review” banners are now much less scary looking; instead of being red, they’re a softer yellow.
  • The old devnews RSS feed now redirects to an appropriate feed providing appropriate content from the Hacks blog.
  • Some style cleanup has been done to the static portions of the site.
  • The feedback link at the bottom of pages no longer links to our long-discontinued forums; instead, they link to a new page on the wiki that explains how to offer feedback, including how to file bugs, get into IRC, and that you can contribute fixes yourself.

A few nice improvements, and the new deployment plan is an interesting development!

 Posted by at 9:58 AM  Tagged with:
Jan 162013

We have a new Kuma platform update tonight! The new version features the following improvements:

  • The following JavaScript keywords are now recognized by the JavaScript syntax highlighter: class, enum, export, extends, interface, let, package, private, protected, static, and yield.
  • The favicon has been updated to get rid of spurious white pixels.
  • The link to the CSS Reference in the Learn section of the site has been updated.
  • Fixed a thumbnail hovering problem on the Dev Derby promotion.
  • Added to the Kuma API a new “toc” command, which returns an ordered HTML list representation of the table of contents for a page.
  • The “Save and Keep Editing” button no longer disappears when you reveal the page metadata editing fields.

Nothing major, but a few nice quality of life improvements.

The core MDN team has been meeting in Austin, Texas this week to plan development work for the next year. I’ll be blogging more about what we’ve come up with next week. We have Plans! Big Plans!

 Posted by at 11:28 PM  Tagged with:
Jan 102013

That’s right! Even though just earlier today I blogged about last night’s Kuma software update on the MDN web site, we have another one. I adore our development team. I could squee all day about this stuff, but instead, let’s have a look at what’s changed:

  • When moving a page, you can now change its title at the same time; this field was previously editable, but its new value was being ignored.
  • The Styles drop-down menu in the editor now includes the “standardSidebar” and “syntaxbox” styles; these are used to create right-floated call-out sidebars and the syntax boxes used near the top of the CSS and (soon) other reference pages, such as HTML.
  • Submenus no longer sometimes stick off the edge of your window if you’re using a right-to-left locale.
  • A formatting problem that could cause ugly wrapping of article version histories has been fixed.
  • More removal of cruft has been done on the development VM.

Not a lot of changes, but several that will be a real boon to select people. In particular, I’m personally thrilled by the improvement to the page move tool, since I’ve been doing a lot of organizational clean-up work lately, and this will streamline that work noticeably. I’m also happy about the update to the Style menu, since these styles are getting used more and more — and being able to avoid dropping into the source editor to apply them is a huge help!

The staff MDN writers and the MDN development team are meeting next week in Austin, Texas to talk about development plans for the next six months or so. I’m looking forward to seeing them all. These are excellent people, and it’s a privilege to work with them all.

 Posted by at 5:14 PM  Tagged with:
Jan 102013

We pushed an update to MDN’s Kuma platform last night. One nice, currently-useful change, one change that has more work left to be done before it’s ready to use, and a few behind-the-scenes tweaks you won’t notice yet.

  • Page moves are more clearly called out on the revision dashboard now, with a little box showing the source and destination pages on each relevant entry.
  • Fixed a bug with choosing a locale in Firefox in the translation UI.
  • The environment variables for a page now include information about which review tags are set on the page. This is a JavaScript Array.
  • Removed obsolete remnant bits of DekiWiki and switched to Ubuntu on our development VMs.
  • Reworked save page logic in preparation to bring back support for editing individual sections in addition to full-page editing.

There are some technical issues involved in getting these lists reported as actual arrays, but that’s something we do hope to do soon.

Other than the bug fix and the revision dashboard change, most of these changes are behind-the-scenes for now (the VM changes and the save logic changes).

In addition, you can’t yet see that tag information for other pages (it’s only available via the current page’s environment variables list). I’m filing a bug for that right now; I didn’t clearly communicate the use cases for this to the development team. Oops.

 Posted by at 10:14 AM  Tagged with:
Jan 082013

We pushed a very small update to MDN’s Kuma software today. There’s only one change: if the text “bug X”, where “X” is a number, appears in an article revision comment, it’s turned into a Bugzilla link to bugzilla.mozilla.org, so you can quickly hop over to that bug for reference.

That’ll be a handy feature! I’ve been looking forward to it for a while now. Enjoy!

 Posted by at 3:53 PM  Tagged with:
Jan 082013

As a leader of a community-driven documentation project such as that which we have on the Mozilla Developer Network (MDN) wiki, part of my job is to help build that sense of community while at the same time trying to make sure that things get done. This can be a tricky balancing act, especially since I go into things with my own ideas of how I think things should be done, and I’m certainly not always right.

For that reason, it’s sometimes a useful exercise to not get involved in debates and discussions about ideas. At times, I try to simply observe and see where the conversation goes. I let the conversation run its course, then jump in until the discussion reaches one of its typical end points:

  1. A consensus is reached. This happens pretty often, and is the best possible outcome of any conversation. If consensus is reached, I hop in and help to ensure that the idea gets implemented (which sometimes starts a whole new discussion about whose job it is to actually take on the decided-upon course of action).
  2. The conversation peters out with no decision. This is also pretty common. If the conversation fades away, sometimes it’s for the best — whatever was being discussed just isn’t that important, or nobody feels like championing it, so it may as well be left alone for the time being. Other times, I’ll step in and give things a nudge to see if I can get the discussion going again.
  3. The discussion devolves into argument. In our community, at least, this doesn’t happen all that often. When it does, I wade in and try to soothe people’s raw nerves and change the tone of the conversation. I can only think of maybe one or two times this has been necessary, though.

It can be incredibly educational to simply follow along while your community thinks out loud. By keeping your biases out of the way, a lot of great things can happen; often ideas come up that you would never have thought of. In addition, it lets your community members exchange ideas more freely, and can help build their sense of belonging. Certainly it helps them feel more confident that you’re not dictating how things should be done!

Silence isn’t always the best policy, but sometimes it’s a useful tool. Used properly, it can help your community become stronger.

 Posted by at 1:48 PM