Feb 102014

On Friday, I blogged about how to go about ensuring that material that needs to be documented on the Mozilla Developer Network site gets taken care of. Today, I’m going to go over how you can tell if something should be documented on MDN. Believe it or not, it’s not really that hard to figure out!

We cover a lot on MDN; it’s not just about open Web technology. We also cover how to build and contribute to Firefox and Firefox OS, how to create add-ons for Firefox, and much more.

A quick guide to deciding where documentation should go

The quick and dirty way to decide if something should be documented on MDN can be summed up by answering the following questions. Just walk down the list until you get an answer.

  • Does this information affect any kind of developer at all?
    • If the answer is “no,” then your document doesn’t belong on MDN, but might belong on SUMO.
  • Is the information about a technology that has reached a reasonably stable point?
    • If the answer is “no,” then it may eventually belong on MDN, but not yet. You might want to put your information on wiki.mo though.
  • Is the information about a Web- or app-accessible technology, regardless of browser or platform?
    • If “yes,” then write about it on MDN!
  • Is the information about Mozilla platform internals, building, or the like?
    • If “yes,” then write about it on MDN!
  • Is the information about Firefox OS?
    • If “yes,” then write about it on MDN!
  • Is the information about add-ons for Firefox or other Mozilla applications?
    • If “yes,” then write about it on MDN!
  • If you get to this line and haven’t gotten a “yes” yet, the answer is probably “no.” But you can always ask on #mdn on IRC to get a second opinion!

A more detailed look at what to document on MDN

Now let’s take a more in-depth look at what topics’ documentation belongs on MDN. Much of this information is duplicated from the MDN article “Does this belong on MDN?”, whose purpose is probably obvious from its title.

Open Web technologies

It should be fairly obvious that we document any technology that can be accessed from Web content or apps. That includes, but isn’t limited to:

Important: It doesn’t matter if these technologies are implemented by Mozilla. Indeed, we even document technologies that are non-standard and only implemented by other browsers (case-in-point, we document a number of WebKit-specific CSS properties). All that matters is that the technology or API is exposed to any content on any browser or platform.

This also includes APIs that are specific to Firefox OS, even those that are restricted to privileged or certified apps.

Firefox OS

An important documentation area these days is Firefox OS. We cover this from multiple perspectives; there are four target audiences for our documentation here: Web app developers, Firefox OS platform developers, developers interested in porting Firefox OS to new platforms, and wireless carriers who want to customize their users’ experience on the devices they sell. We cover all of these!

That means we need documentation for these topics, among others:

  • Open Web apps
  • Building and installing Firefox OS
  • Contributing to the Firefox OS project
  • Customizing Gaia
  • Porting Firefox OS

The Mozilla platform, Firefox, and add-ons

As always, we continue to document Mozilla internals on MDN. This documentation focuses primarily on developers building and contributing to projects such as Firefox, as well as add-on developers, and includes topics such as:

  • Gecko
  • XUL
  • Building and configuring Firefox
  • Add-ons (extensions, plug-ins, and themes)

What don’t we cover?

There’s one last thing to consider: the types of content we don’t include on MDN. Your document doesn’t belong on MDN if the answer to any of the following questions is “yes.”

  • Is it a planning document?
  • Is it a design document for an upcoming technology?
  • Is it about a technology that’s still evolving rapidly and not yet “ready for prime time?”
  • Is it a proposal document?
  • Is it a technology that’s not exposed to the Web and is specific to a non-Mozilla browser? If it’s not exposed to the Web, but is part of Mozilla code, then you just might want to document it on MDN.


Hopefully this gives you a better feel for the kinds of things we document on MDN. If you learned anything, I’ve done my job.

Over the next few days, I’ll be continuing my blitz of documentation about documentation process, how to help ensure the work you do is documented thoroughly and well, and how to get along with writers in general.

 Posted by at 4:57 PM
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