Feb 072014

If you’re a contributor to the Firefox project—or even a casual reader of the Mozilla Developer Network documentation content—you will almost certainly at times come upon something that needs to be documented. Maybe you’re reading the site and discover that what you’re looking for simply isn’t available on MDN. Or maybe you’re implementing an entire new API in Gecko and want to be sure that developers know about it.

Let’s take a look at the ways that you can make this happen.

Requesting documentation team attention

In order to ensure something is covered on MDN, you need to get the attention of the writing team. There are two official methods to do this; which you use depends on various factors, including personal preference and the scope of the work to be done.

The dev-doc-needed keyword

For several years now, we’ve made great use of the dev-doc-needed keyword on bugs. Any bug that you think even might benefit from (or require) a documentation update should have this keyword added to it. Full stop.

Important: The sooner you add the dev-doc-needed keyword, the better. Don’t wait until the patch lands to add it! If we know about the change that’s on the way, we can plan for it in our documentation schedule more efficiently, which will reduce lag time in getting the writing done! Also, be sure to add dev-doc-needed keyword to bugs for enabling an API that was previously preffed off. Otherwise we may miss this important documentation change.

Documentation request bugs

The other way to request developer documentation is to file a documentation request bug. This can be used for anything from simple tweaks to documentation to requesting that entirely new suites of content be written. This can be especially useful if the documentation you feel needs to be created encompasses multiple bugs, but, again, can be used for any type of documentation that needs to be written.

Getting ahead: how to get your request to the top of the pile

Just flagging bugs or filing documentation requests is a great start! By doing either (or both) of those things, you’ve gotten onto our list of things to do. But we have a lot of documentation to write: as of the date of this blog post, we have 1233 open documentation requests. As such, prioritization becomes an important factor.

You can help boost your request’s chances of moving toward the top of the to-do list! Here are some tips:

  • If your technology is an important one to Mozilla’s mission, be sure to say so in your request. Let us know it’s important, and why.
  • Give us lots of information! Be sure we have links to specifications and design documents. Make sure it’s clear what needs to be done. The less we have to hunt for information, the easier the work is to get finished, and the sooner we’re likely to pick your request off the heap.
  • Ping us in IRC on #mdn. Ideally, find the MDN staff member in charge of curating your topic area, or the topic driver for the content area your technology falls under, and talk to them about it.
  • Email the appropriate MDN staff member, or ping the dev-mdc mailing list, to let us know about your request.
  • For large new features or technologies, try to break up your request into multiple, more manageable pieces. If we can document your technology in chunks, we can prioritize sections of it among other requests, making it easier to manage your request efficiently.

I’ll blog again soon with a more complete guide to writing good documentation requests.


Be sure to check out the article “Getting documentation updated” on MDN; this covers much of what I’ve said here.  Upcoming posts will go over how to decide if something should be covered on MDN at all, and how to communicate with the developer documentation team in order to make sure that the documentation we produce is as good as possible.

 Posted by at 11:49 AM
Feb 062014

The first step in the process of beginning to properly curate the content on MDN is for us to inventory and evaluate our existing content. This lets us find the stuff that needs to be updated, the pages that need to be deleted, and the content that we’re outright missing.

We’re still working on refining the details of how this process will work—so feel free to drop into the #mdn channel to discuss your ideas. That said, there are some basic things that clearly need to be done.

Each of the content curators will coordinate this work in each of their topic areas, working with other community members, the topic drivers for the subtopics in those topic areas, and anyone else that wants to help.

Eliminate the junk

First, we need to get rid of the stuff that outright doesn’t need to be on MDN. There are a few categories of this:

  • Content already marked as “junk”.
  • Inappropriate or spam content.
  • Dangerously wrong content.
  • Duplicate pages; sometimes people create a new page that replicates content that already exists. We need to decide which one is best in these cases and get rid of the others. This will sometimes involve merging bits of useful content from multiple pages together first.
  • Select dangerously obsolete content. In general, we try to preserve obsolete content, instead labeling it as such. However, if the content is actually dangerous in some way, we may consider actually removing it entirely.

Develop an organization plan

The next task is to finalize our content organization plan. We’ve been discussing this plan for a long, long time now, and in fact in the summer of 2013, we finalized a plan. Unfortunately, when we started to actually implement it, we realized that in practice, it’s rather confusing. So we’re going to take another crack at it to resolve the frustrating and confusing aspects of our hierarchy plan. In particular, there are aspects of our new Web platform documentation layout that just didn’t work in the real world, and we’ll be working to fix that soon.

As soon as this organization work gears up in earnest again, you’ll know, because we’ll be asking for help!

Move content to where it belongs

Once we know what the site layout is going to be, we need to start moving content so that everything is in the right place. This involves two activities.

First, we need to move content that’s already been organized once into the new correct places. Most content that’s already been recently reorganized probably is in the right place already, or at least close to it. We just need to go through all this material and make sure it’s in its final, correct home under the new site layout.

The second, and much bigger, job is to go through the many thousands of pages that have never been properly organized and move them to where they belong. We have entire sets of documentation content that are entirely located at the top of MDN’s content hierarchy, even though they belong in a subtree somewhere. These need to be found and fixed.

For example, most of the documentation of Gecko internals is actually located at the top of the site’s hierarchy. Likewise with NSPR documentation, among others. All of that needs to be moved to where it should be.

In many cases, this will also involve building out the site hierarchy itself; that is, creating the landing pages and menus that guide readers through levels of material until they reach the specific documentation they’re looking for. That’s for people like me, that like to browse through a documentation set until they find what they want, instead of relying entirely on search.

What’s incomplete?

The next step is to go through these pages and figure out which ones aren’t complete, or are in need of updates. There are plenty of these. We need to label them appropriately and file documentation request bugs to get them on the list of things to be updated.

What’s missing?

Once all of that is done, we need to go through each topic area and figure out what material is missing. What APIs are entirely undocumented? What method links go to empty pages? What pages are just stubs with no useful information? What technologies or topics are missing tutorials and examples?

All of these are things we need to catalog so that we can close the gaps in our documentation.

There’s lots more to be done, but this article is long enough. We’ll take a look at some of the other tasks that need to be taken on in future posts.

 Posted by at 10:56 AM
Feb 052014

MDN is big. Really big. There are many thousands of pages just in English; once you add in all the various localizations, you’re talking about tens of thousands of pages of content.

A lot of it is excellent. Some of it is merely “good.” And some of it is really, really out of date or useless. The problem is, we don’t always know which is which, since there’s so much of it.

As part of our “year of content,” we’re going to be buckling down and poring over the existing material on MDN, locating the stuff that’s just awful and either fixing it or getting rid of it. We’re going to also clean up and improve the good stuff to make it great. And we’re going to make sure everything is in the right place, tagged properly, and easy to find.

This is going to be a big project.

To help ensure we’ve got a handle on what’s going on across the breadth of topics MDN covers, each MDN writing staff member has voluntarily taken on a broad topic area to be responsible for curating:

  • Firefox (desktop and mobile): Will Bamberg
  • Firefox OS: Chris Mills
  • Web Platform
    • APIs: Eric Shepherd
    • CSS: Jean-Yves Perrier
    • HTML: Jean-Yves Perrier
    • JavaScript: Florian Scholz
    • Others (SVG/MathML/etc): Florian Scholz
  • Web apps: Chris Mills
  • Developer tools: Will Bamberg
  • Other Mozilla-specific topics
    • Marketplace: Chris Mills
    • Games: Chris Mills
    • Thunderbird: no owner at this time
    • L20n: Chris Mills
    • Emscripten: Chris Mills
    • Persona/Firefox accounts: Will Bamberg
    • Learning Web development: Chris Mills
  • MDN community and how-to-document content: Janet Swisher and Eric Shepherd

You may have noticed that Thunderbird documentation has no curator. Given that this is now a community-driven project, we decided against assigning a staff writer to curating Thunderbird’s content. If the Thunderbird team would like to assign someone, please let me know!

I’ll blog in the next few days about the process by which our content curation effort will be handled. Until then, let’s keep on building the best documentation on the Web!

 Posted by at 10:45 AM
Feb 042014

The last few years have been very busy for the Mozilla Developer Network community. In addition to all the writing and documentation work we’ve managed to do, we’ve had additional major projects going on each year:

  • 2012 was the year of the Kuma project, building and launching a new MDN based off a home-grown platform to better serve our needs in documenting both the open Web and the Mozilla project.
  • 2013 was the year of the redesign; we spent much of our time last year designing, building, testing, and deploying the MDN site redesign, making MDN more attractive and user-friendly than ever before.

Unfortunately, with all these huge (yet incredibly awesome and important) projects going on, we’ve not gotten as much done on documentation as we’d have liked. That’s why we’ve decided that 2014 will be the “year of content.”

Our goal for this year is to get caught up on documenting things we’ve fallen behind on and to improve the existing material already on MDN. I’ll be blogging more about what we’ll be doing for the “year of content” soon. In the meantime, if you contribute to MDN (and if you don’t, shame on you!), think about things you know of that need to be fixed. Start making a list. Your ideas are needed, and we’ll be diving into this work soon!

 Posted by at 12:05 PM
Feb 032014

A recent initiative for the development of the Kuma software powering the Mozilla Developer Network (MDN) site is that we are going to be maintaining a list of the top five “paper cut” bugs that we’d like the dev team to find time to fix. These won’t have a schedule attached to them, and will only be worked on when other, priority items are fixed, but will each have a huge impact on the site’s usability, functionality, or simple friendliness.

During the MDN writing staff meeting (about which I’ll be blogging over the next few days), we pored over the long list of pending MDN bugs and selected the five we’d like to see the development team try to tackle as time allows.

I think you’ll agree that each time one of these is fixed, there will be celebratory riots in the streets!

 Posted by at 5:29 PM
Jan 062014

Getting back to work after a long break is always odd. It’s especially strange this time, since all of Mozilla was closed for two weeks. Takes a while to get a big ship moving again after being in dry dock for a while.

Looking forward to a very crazy busy and productive month: a couple weeks of catch-up work and work on the MDN user guide materials, then on-site writer staff meetup for 2014 planning (I expect to do some video meetings too, for community involvement). Then a couple days visiting family before returning to the SF office to hang with a multi-team dev work week for a couple days, to give insights on the writing process and ways devs can help make docs processes go better.

My personal goals for MDN, content-wise, for the coming year revolve largely around ease-of-use: improving documentation about how to use MDN, guiding the development team toward making MDN easier to use, fixing site organization problems, and encouraging more developers and development teams to be more actively engaged with the documentation process.

I also hope to do more blogging about working in documentation as a field, how to be a technical writer, and the like. I feel that I have insights there that might be useful, and that I should try to share them.

It’s going to be a great year for MDN — I fully expect that people are going to be really impressed with, and excited by, all the improvements we’ll continue to make over the coming months.

On a personal note, my ability to get back up to speed is being seriously impacted by my being at a high point in my pain cycle. It also doesn’t help that my pain goes up faster the more I type. Next week, I will be seeing an orthopedic surgeon to investigate the possibility of a structural problem of some kind in my shoulder. That would be lovely, to have that on top of the existing nervous system problems, but it would at least be something that can probably be fixed!


 Posted by at 1:25 PM
Dec 132013

We’ve pushed a number of updates to Kuma (the software that powers the MDN web site) lately. Here are a few of the more interesting changes:

  • Our redesigned user experience has launched! Key features include a new, more attractive look and feel, sidebar navigation in several areas of the site to help you get around specific APIs and technology areas, and more.
  • A new search engine is in place, which not only searches better, but provides filters to let you narrow down your search more easily.
  • Pages’ tables of contents no longer have numbers next to each item, and items are indented by heading level. This will make the TOCs much more readable.
  • A bug causing menus to be cut off on mobile devices has been fixed.
  • A bug causing horizontal scrolling on mobile devices has been fixed.
  • The initialization of “Tabzilla” (the unified Mozilla tab at the top of the page) is now done in a different place, which will improve page load performance.
  • We’ve removed some unused CSS and JavaScript, which hopefully will help load times a little bit.
  • The “Interested in reading this offline” link that took you to a page suggesting you download some apps that just provide a different way to read MDN has been removed. This was an experiment that somehow never ended.
  • When editing profiles, the correct email address is now displayed.
  • Several legacy files have been removed.

There’s a ton of nice improvements! The team will be focusing on fixing performance issues for the next few weeks. Other stuff will be happening too, but we’re going to make a big push to try to improve our load times.

 Posted by at 5:15 PM
Dec 092013

Today we launched the new design for the Mozilla Developer Network Web site. We’ve been working on this for a long time, with discussions starting as much as a year ago, and actual coding starting this past summer. It was a huge effort involving a ton of brilliant people, and I’m thrilled with the results! Not only is the new design more attractive, but it has a number of entirely new features that will help you find what you want—and read it—more easily, and in more places, than ever before.

Updated home page

The new home page has a completely revamped organization, with a large search box front and center. Below that are links to key areas of the MDN Web site, including much of our most-used documentation, such as the JavaScript, CSS, and HTML docs, content about Firefox OS and developer tools, and the brand-new Mozilla Developer Program, whose goal is to help Web developers learn more and more quickly.

MDN home page screenshot

Zoning in

You may notice the new concept we call “zones” in the screenshot above. A “zone” is a new concept we’ve added, wherein we can construct a special topic area that can accumulate documentation and samples from across MDN to cover that topic. For example, the Firefox OS zone provides documentation about Firefox OS, which involves not only Firefox OS-specific content, but information about HTML, CSS, and so forth.

Screenshot of the Firefox OS zone landing page

Here you see our new zone navigation bar along the left side of the screen, promotional boxes for specific content, and lists of key articles.

Search and ye shall find

Search has been significantly improved; we now have an on-site search powered by Elastic Search rather than using Google, which lets us customize the search in useful ways. One particularly helpful feature is the addition of search filters. Once you’ve done a search, you can narrow the search further by using these filters. For example, here’s a search for “window element”:

Screenshot of search resultsWell. 5186 results is a lot. You can use our new search filters, though, to narrow those results down a bit. You can choose to restrict your search to one or more topic areas, types of document, and/or skill level. Let’s look for articles specifically about the DOM:

Screenshot of search resultsIt’s worth noting here that these filters rely on content being tagged properly, and much of our content is still in the process of being tagged (especially regarding skill level). This is something we can always use help with, so please drop into #mdn on IRC if you’re interested in helping with this quick and easy way to help improve our search quality!

Responsive design

An area in which MDN was sorely lacking in the past was responsive design. This is the concept of designing content to adapt to the device on which it’s being used. The new MDN design makes key adjustments to its layout based on the size of your screen.

 Screenshot of the Firefox zone landing page in "desktop" view.  Screenshot of the Firefox zone landing page in "small desktop" view. Screenshot of the Firefox zone landing page in "mobile" view.
Here’s the Firefox zone’s landing page in standard “desktop” mode. This is what you’ll see browsing to it in a typical desktop browser environment. Here’s what the same page looks like in “small desktop” mode. This is what the page looks like when your browser window is smaller, such as when viewing on a netbook. And here’s the same page in “mobile” view. The page’s layout is adjusted to be friendlier on a mobile device.

Each view mode rearranges the layout, and in some cases removes less important page elements, to improve the page’s utility in that environment.


The last new feature I’ll point out (although not the last improvement by a long shot!) is the new quicklink feature. We now have the ability to add a collection of quicklinks to pages; this can be done manually by building the list while editing the page, or by using macros.

Here’s a screenshot of the quicklinks area on the page for the CSS background property:

Quicklinks in the CSS reference.

The quicklinks in the CSS reference provide fast access to related properties; when looking at a background-related property, as seen above, you get quick access to all of the background-related properties at once.

There’s also an expandable “CSS Reference” section. Clicking it gives you an alphabetical list of all of the CSS reference pages:

CSS reference page with expanded links to other pages in the reference.

As you see, this lets you quickly navigate through the entire CSS reference without having to backtrack to the CSS landing page. I think this will come as an enormous relief to a lot of MDN users!

To top it off, if you want to have more room for content and don’t need the quicklinks, you can hide them by simply clicking the “Hide sidebar” button at the top of the left column; this results in something like the following:

CSS reference page with the left sidebar closed.The quicklinks feature is rapidly becoming my favorite feature of this new MDN look-and-feel. Not all of our content is making full use of it yet, but we’re rapidly expanding its use. It makes navigating content so much easier, and is easy to work with as a content creator on MDN, too.

Next steps

Our development team and the design and UX teams did a fantastic job building this platform, and our community of writers threw in their share as well: between testing the changes to providing feedback, not to mention contributing and updating enormous amounts of documentation to take advantage of new features and to look right in the new design, I’m enormously proud of everyone involved.

There’s plenty left to do. There are new platform features yet to be built, and the content always needs more work. If you’d like to help, drop into #mdn to talk about content or #mdndev to talk about helping with the platform itself. And feel free to file bugs with your suggestions and input.

See you online!

 Posted by at 3:12 PM
Nov 122013

A new push of the Kuma code to the MDN web site was done yesterday, followed by another this morning. Here’s a quick look at what’s new.

  • Page moving has landed again at last. This is for now available only to administrators, I believe. The emails that let you know when page moves have finished don’t always send correctly due to what appears to be a server configuration problem. We have a bug filed for IT to look at it.
  • The Elastic Search indexing task has been rate-limited so it doesn’t chew up so many resources that it blocks other tasks from running.
  • We can add the attribute data-default-state="open" to quicklink “folder” items to make them default to open rather than closed.
  • Redirects and user pages are no longer shown in search results, which makes the search results much better. This will require a site index rebuild, so you may not see this improvement right away.
  • Names in user profiles now have wider letter spacing.
  • The capitalization of the “See also” heading in the sidebar above quicklinks has been corrected, and the link color is being enforced on the quicklinks box.
  • Fixed the demo studio links to draw above the spotlight image so that they’re clickable.
  • Content tables now all have a bottom margin.
  • The “Previous Page” and “Next Page” buttons in the search results are now just “Previous” and “Next”.
  • Other assorted style cleanup work has been done.

This is a big deal, in that we finally have page moves. We’ll use it cautiously at first, to avoid (hopefully) any disasters if new bugs are found. But we’re pretty confident this time, other than the server issue with failing confirmation emails.

 Posted by at 1:04 PM  Tagged with:
Nov 082013

We’ve just pushed another update to the Kuma platform deployed on MDN! Let’s take a look at an overview of what’s been done:

  • Page move now correctly disallows attempts to move pages to a URL for which there is no parent page.
  • Page move is now constrained to a single locale.
  • Template (macro) pages no longer have a language selection menu, since these are always edited in the en-US locale and are localized in their code.
  • When viewing on a mobile phone, MDN is now presented in a 1-column view.
  • The list of search filters on search results pages now has an empty checkbox drawn when not selected; previously there was no indicator until you selected each filter.
  • The height of the sidebar “See also” box has been corrected in “small desktop” layout.
  • Updated the appearance of the search box in the header area.
  • Rendering of the language drop-down has been improved so that parentheses are no longer in the wrong place in RTL languages.
  • Corrected the layout of the search results page in right-to-left locales.
  • Improve heading structure on the homepage to put items in the correct order for screen readers.
  • Microdata has been implemented for breadcrumbs for Google search results.
  • The left margin has been removed on the first navigation item, and its submenu shadow has been lightened.
  • The home-globe.svg image used on the home page has been replaced with a PNG to save bandwidth.
  • PNG images have been optimized to save bandwidth.
  • The padding at the bottom of the <li> element has been tightened up.
  • Platform localization docs have been updated a bit.

Whew! That’s quite a list! As you can see, page move is getting there. It’s technically done, but we’ve run into a clash with another process that needs to be resolved before we start using it in the field. Soon, I hope!

 Posted by at 3:39 PM  Tagged with: