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
  • XPCOM
  • 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.

Wrap-up

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

  One Response to “What documentation belongs on MDN?”

  1. […] Seriously. There aren’t that many of us on the writing team, even including our awesome non-staff contributors. We sadly don’t have enough time to become experts at all the things that need to be documented on MDN. […]