Does this belong on MDN?

If you're preparing to document something, you may be trying to decide where to put the information. There are several places that documentation can go, and while MDN is among the largest documentation repositories on the Web, it's not the only one. In addition, you may be considering maintaining documentation in your source code, putting the document on the Mozilla wiki, or in readme files in a git repository. This article's purpose is to help you decide which of these courses of action is right for your content.

What belongs on MDN?

We cover an incredible variety of material on MDN. But there are a few things that outright don't belong on MDN, too. This section will help you figure out if MDN is a suitable home for your documentation.

Things that MDN covers

We cover a lot of stuff on MDN; in general, if it's a completed or shipping product from Mozilla, or open Web-facing technology, we document it on MDN, in and out.

Here's a taste of some of the things we cover; this isn't a complete list but will give you some idea:

  • Open Web technologies
    • HTML
    • CSS
    • JavaScript
    • Web-facing APIs
    • etc.
  • Firefox OS
    • Open Web apps
    • Building and installing Firefox OS
    • Contributing to the Firefox OS project
    • Customizing Gaia
    • etc.
  • The Mozilla platform
    • Gecko
    • Building and configuring Firefox
    • XUL
    • XPCOM
    • etc.

Note: It's important to note that we cover even non-Mozilla technologies if they're exposed to the Web; we have documentation for WebKit-specific CSS properties, for example.

Things we don't cover

There are a few simple questions you can ask to determine that something outright should not be documented on MDN:

  • Is it a planning document?
  • Is it a design document for an upcoming technology?
  • Is it a project proposal?
  • Is it a raw specification?
  • Is it a technology that's not exposed to the Web but is specific to a non-Mozilla browser?

If you answer "yes" to any of these questions, the documentation does not belong on MDN. If you answer "no" to all of them, you should seriously consider putting the documentation on MDN!

Advantages to documenting on MDN

There are a lot of good reasons to document content on MDN.

Lots of writers

The MDN community is big. Really big. It's big in the sort of way that makes big things look small. Seriously, we have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, I'm not sure about Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:

  • We have a paid staff of writers whose mission is to make sure that our content is as good as possible.
  • We have a core community of volunteers who contribute substantial amounts of content and can help you.
  • In fact, you have a good chance of getting someone else to do most or all of your writing for you!
  • The broader MDN community also contributes enormously; from typo fixes to editorial reviews of your content, they can save your bacon.
  • The #mdn channel offers a resource where you can talk to our writing community and get their advice, or recruit help with the production of or maintenance of your content.
  • Because we have contributors all over the world, there's always someone around, watching for problems and fixing them.

Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.

Maintenance

Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:

Delete spam
Spam happens. We deal with it.
Copy editing
You don't have to worry if your writing isn't as good as you'd like. We'll turn your prose into something other people can read.
Consistency of style
We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.
Content management
Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.

Cases for documenting elsewhere

There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. We'll look here at some of those reasons, and the pros and cons for each.

Plans and processes

Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple.

The project is on Github

Some of Mozilla's projects are hosted on Github, and Github offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:

  • The MDN docs team will probably not be able to help you. We don't generally participate in documentation work off MDN; there are exceptions but they are rare.
  • Cross-linking your documentation with other relevant materials may be difficult or impossible.
  • The content will not have consistent style with other documentation.
  • Your documentation loses discoverability by not being among other documentation.
  • Github-hosted docs are generally not as attractive and/or readable as those hosted on MDN.

It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind keeping their own docs, or are working on code that has minimal documentation needs.

You want to keep docs in-source

Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects. This has the advantage of letting the developers document their technology as they code it. There are some drawbacks:

  • The MDN docs team can't help you; even if the code is within Mozilla's source repository, the system of reviews and check-ins make it impractical for the docs team to participate.
  • You don't have easy tools for cross-linking with other relevant documentation. Cross-linking provides both context and additional important information to your readers.
  • Your documentation loses discoverability by not being among other documentation.
  • Even if you use conversion tools (like JavaDoc) to create Web-readable documentation, it won't be as attractive as what we can do on MDN.

Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.

In the future

It's worth mentioning that someday we intend to make it possible to present off-site content as if it were part of MDN, and that we hope to one day have tools to actually import content from other sites onto MDN. However, there's no timeline in place for making this happen, and even once it does, it will not be as effective as building the documentation directly on MDN.

Document Tags and Contributors

Contributors to this page: Sheppy, heathhamilton
Last updated by: Sheppy,