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:
- Open Web apps
- CSS
- HTML
- JavaScript
- APIs (the DOM, WebGL, WebSockets, IndexedDB, etc)
- MathML
- SVG
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.