Mar 142014
 

Last weekend, we had an MDN work weekend at Mozilla’s Paris space. Over the course of the three days—Friday, Saturday, and Sunday—we built code, wrote and updated documentation, and brainstormed on new and better ways to present documentation on MDN. A grand total of 34 participants (wow!) including 16 volunteers and 18 paid Mozilla staff sat down together in a big room and hacked. 11 countries were represented: France, the United States, Canada, the United Kingdom, Sweden, Italy, Spain, Poland, Germany, India, Bangladesh, and Brazil. We completed 23 projects and touched (either adding, updating, or closing) over 400 bugs.

The most important thing, to me, was the reminder that our community is a real, tangible presence in the world, rather than an ephemera that flits about touching documentation from time to time. These people have real jobs, having real and important impacts on their local communities. Coming together is a chance to enhance our bond as Mozillians. That’s a great thing.

What’s also great, though, is the amazing amount of output we produced. Let’s look over some of the stuff that went on (if I leave out something you did, I apologize!).

Documentation work

  • Prototyped new UX for the MDN App Center.
  • All KumaScript errors on every page in the English, German, and French locales were resolved! This is a huge deal and I’m grateful to Jean-Yves, Florian, and Sphinx for this work.
  • Lots of work was done to sketch out and plan an improved onboarding experience for new contributors.
  • Lots of new Web documentation was added for various CSS properties, as well as for the HTML <template> element used by Web Components.
  • Over 100 pages of beginner content were properly tagged to be easier to find using MDN’s search filters.
  • Planning work for the new MDN “Learning” area was done; this area will provide content for new Web and Web app developers.
  • Work to plan out requirements for future MDN events was done.
  • Planning for the next steps of the compatibility data project was done; I missed this meeting although I meant to be there. We will be building a system for maintaining a database, in essence, of compatibility for all the things that make up the Web, then updating our compatibility tables to be constructed from that database. This database will also be queryable.
  • Progress was made on documenting the Web Audio API. Thanks to Scott Michaud for his work on this.
  • Chris Heilmann worked on adding live samples to pages; his work included some experiments in ways to make them more interactive, and he talked with our dev team about an improved user interface for implementing live samples.

Kuma platform work

Seven new people had the Kuma build system set up on their computers, with a virtual machine running a Kuma server up and running. Those seven people included me. In fact, I devised and submitted three patches to the Kuma platform over the weekend! They’re nothing particularly big, but it did allow closing three longstanding minor bugs. Not a big deal, but I’m proud of that anyway.

And I’m not the only one: a ton of amazing enhancements to the Kuma platform were developed over the weekend. Some are already deployed; others will not be for a while, since there are quirks to iron out.

  • Live samples are now better delineated by having a border drawn around them (this one is mine, and already deployed).
  • A new JavaScript snippet has been developed that can be embedded into any Web site to automatically link common terms to the appropriate pages on MDN. This is almost but not quite ready to deploy as I write this.
  • A bunch of old code we inherited from the Kitsune project has been removed (Ricky did this).
  • The email sent to admins after a page move operation is completed has been enhanced to include a link to the new location and to have the subject be more specific as to which move finished (another of mine; not yet deployed but probably will go out in the next push).
  • The “revert this page” confirmation prompt has some wording corrections (mine, and pushed to production).
  • A new “top contributors” widget has been developed; this will show the top three contributors to a page, with their avatar image, at the top of the page somewhere. This isn’t finished but the prototype is promising. This work was done primarily by Luke Crouch, I believe.
  • UX design work was done for future enhancements to how we display search results.
  • UX design work was done for how we display the language list, to improve discoverability both of the fact that there are multiple languages, but also that pages can be localized by contributors.
  • The revision diff page you get when comparing two pages in an article’s history now includes a “Revert to this revision” button. Also mine; I don’t know if it’s on production yet but I think so.
  • Lots of design and planning work for improved search UX, filtering, and more. This stuff will amaze you when it lands!

I won’t become a huge contributor to Kuma, probably. I don’t have time. I’m too busy writing and (more often, really) organizing other writers. That’s okay, of course. I’m having my own impact on our worldwide community of Mozillians and users and developers on the World Wide Web.

 Posted by at 6:47 PM
Feb 212014
 

The most important rule of contributing to the developer documentation on MDN is this:

Don’t be afraid to contribute, even if you can’t write well and can’t make it beautiful. It’s easier for the writing team to clean up information written by true experts than it is to become experts ourselves.

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.

Even if all you do is copy your notes onto a page on MDN and click “Save,” that’s a huge help for us. Even pasting raw text into the wiki is better than not helping at all. Honest!

We’ll review your contribution and fix everything, including:

  • Grammar; you don’t have to have perfect (or even good) writing skills—that’s what the writing team is here for!
  • Style; we’ll make sure the content matches the MDN style guide.
  • Organization; we’ll move your content, if appropriate, so that it’s in the right place on the site.
  • Cross-linking; we’ll add links to other related content.
  • Structure and frills; we’ll ensure that the layout and structure of your article is consistent, and that it uses any advanced wiki features that can help get the point across (such as live samples and macros).

It’s not your job to make awesome documentation. That’s our job. So don’t let fear of prevent you from sharing what you know.

 Posted by at 10:15 AM
Feb 202014
 

Among the first steps we need to take for our “Year of Content” this year is to review our existing documentation to find where improvements need to be made. This involves going through articles on MDN and determining how “healthy” they are. If a doc is reasonably healthy, we can leave it alone. If it’s unhealthy, we need to give it some loving care to fix it up.

Today, I’d like to share with you what constitutes a healthy document. Only once we know that can we dive into more depth as to how to fix those articles that need help.

Check the content’s age

Look to see how recently the content was updated. If it’s been a long time, odds are good that it’s out of date. The degree to which it’s out of date depends, of course, on what the topic is and whether or not there’s been development work in that area recently. Content about CSS is a lot more likely to go quickly stale than material about XPCOM, for example.

Review articles in areas of the site, looking to see how long it’s been since it was last changed, and use your judgement as to whether it’s been too long.

Do the pages have quicklinks?

Quicklinks appear in the left sidebar on MDN pages to offer links to related content. We are in the process of phasing out the old “See also” block at the end of articles in favor of quicklinks. If you see pages that have a section entitled “See also”, they need to be updated. Similarly, many areas of the site have standard quicklink macros that should be used, such as HTMLRef or CSSRef. These automatically construct advanced sidebars which link to related material as well as all other HTML elements or CSS properties.

Pages with no “See also” section or quicklinks may need some added; it’s often useful to provide additional links like these. However, they’re not mandatory.

Are there any KumaScript errors?

This is a big one. Any page that presents a big red KumaScript error box at the top of the page is an immediate “drop everything and fix this” alert. If you don’t know how to fix these (or aren’t able to), visit #mdn on IRC or drop me an email.

Are there appropriate examples and images?

Developers learn best and fastest by example. Any page about a developer technology that doesn’t have good code samples—with explanations of how they work—is probably flawed. Take note of pages that are missing examples, or have overly simplistic (or excessively complicated) examples. Also, most examples should be presented using our live sample system, which allows us to demonstrate inline the results of executing a piece of code.

Similarly, if an article would benefit from screenshots or other images (or videos) to help explain a topic, and doesn’t have any, that’s a detriment to its health, too.

Are there compatibility tables?

Every page about an API or technology should have a compatibility table that indicates what browsers and platforms support it. This includes both tutorials and reference pages. If these are missing, users will have a hard time evaluating whether or not a technology is ready for prime time.

On a related note, pages that are written from the perspective of using them from a particular browser are also flawed. Much of our content is still very Firefox-specific, which isn’t appropriate. MDN’s content should be browser-agnostic, supporting our developers regardless of what platforms and browsers their users are on. We need to find and get rid of boxes and banners that say a technology was added in Firefox version X and move that information into proper compatibility tables.

Do reference pages link to specifications?

Every reference page should include a link to the specification or specifications in which that API was defined. We have a standard table format for presenting this information, as well as a set of macros that help construct them.

Are pages formatted properly?

All pages on MDN should follow our style guide. Admittedly, our style guide is a bit in flux at the moment, and not all of it is written down yet. However, that will change soon (certainly by the time we dive in deeply into this work), so it deserves mentioning here. Content that deviates from the style guide needs updating.

Important: Many older parts of MDN use custom styles, or embed CSS examples within the body of articles. This is no longer allowed, and in fact the ability to edit content like this will eventually go away, so it’s important that these pages be updated to use only our standard styles, and to move all examples into live samples.

Are pages tagged correctly?

Increasingly, we’re using macros for everything from generating landing pages and menus to search filtering to building to-do lists. This depends heavily on pages being tagged correctly. Articles that don’t follow our tagging standards need to be updated so that all of these features of the MDN Web site work correctly.

Do pages need review?

Healthy articles have been fully reviewed; they have no review requests flagged for them. New articles are automatically flagged for both editorial and technical review, and these reviews may be requested at any time after the article has been created, as well. These reviews help to ensure the documentation’s quality and clarity.

Make sure there aren’t any dead ends

Every article should have links to other pages. Articles that don’t cross-link properly to other content become dead ends in which users get lost. Be sure that terms are properly linked to relevant content elsewhere on MDN; if there aren’t appropriate links to other pages, the articles aren’t healthy.

Do pages use macros properly?

We use macros on MDN for a lot of things. It’s important that they’re used consistently and correctly. By using macros to generate content, we can create more and more consistent content more quickly. For example, when linking to API interface objects, use the DOMXRef macro instead of directly linking to the object’s documentation. This macro can adapt quickly to site changes and design changes. In addition, it automatically creates appropriate tooltips and automatically handles other tasks to improve the site’s usability.

 Posted by at 12:05 PM
Feb 182014
 

A key aspect to the documentation process is communication. Not only is the completed documentation itself a form of communication, but thoughtful, helpful communication is critical to the production of documentation. For the MDN documentation team to create content, we need to be able to interact directly with the developers behind the technologies we write about.

Today I’d like to share with you how that communication works, and how you can help make documentation better through communication. Not only do we need your help to know what to document, but we need information about how your technology, API, or the like works. The less time and effort we have to put into digging up information, the sooner we can have documentation for your project, and the better the coverage will be.

Pro tip: Assume we know nothing about your project. We don’t know who you are, what your technology is or does, or even that it exists. If you start with that assumption, and provide all the information you have, everyone probably wins.

Share details

There is basic information we will almost always need when working on documentation for an API or technology. If you’re proactive about providing this information, it will save everyone time and energy. I mentioned this previously in my post about writing good documentation requests, but it bears repeating:

  • Who are the responsible developers? We will almost certainly have questions, and nothing slows down a writing project like spending two weeks trying to figure out who can answer simple questions.
  • Make sure we have links to the specifications and any design or implementation notes available for the project. We probably will find the specification on our own, but anything beyond that is likely to be missed. And if you send us the spec link (which you probably have memorized by now anyway), you’ll earn our appreciation, which can’t hurt, right?
  • Where’s the code for your implementation? Providing a link (or links) to the code tree(s) on mozilla-central and/or Github can save us tons of time, since we will refer to the code often while writing.
  • When the specification and/or design is finalized, let us know! We usually won’t start writing until the design has settled down into a reasonably stable state, and if we don’t know it’s stabilized, we might never get started. Similarly, if there’s an unexpected change after the specification was supposedly finished up, be sure to ping us then, too!
  • Do you have code samples or snippets? Sharing links to those, or to any tests you’ve written, can help us understand how your API or technology works—and it gives us a head start on writing example code for the documentation.
  • Do you have a schedule? Let us know when you expect to hit your milestones and when you expect to reach each branch.

Looping us in

The more your team is able to integrate the documentation team into your docs process (and vice-versa), the better. It’s actually pretty easy to make us feel at home with your team. The most important thing, of course, is to introduce your project to the writer(s) that will be working on documenting it.

To find out who will most likely be writing about your project or API, take a look at our topic drivers list on MDN. If you’re unable to figure it out from there, or don’t get a reply when you ping the person listed there, please feel free to ask me!

  • Invite us to attend any planning or status meetings for your project. Don’t assume we know about them (we probably don’t, unfortunately). Being able to listen in on your meetings (and occasionally even offer suggestions) is incredibly helpful for us. We see a lot of APIs, and you never know, we might have ideas you can run with.
  • Be sure we know what mailing list or mailing lists your team has discussions on. We will probably either want to become regular readers or at least be able to quickly pull up archives while doing research.
  • Let us know what IRC channels we should hang out in to participate in discussions about your project or the technology you’re working on.
  • Do you have work weeks? Invite us to join you! Having a writer attend your work week is a great opportunity to interact and get some face-to-face discussion in about the documentation, what you need, and what you’d like to see happen.
  • Whenever someone blogs about the project, technology, or API, let us know. Don’t assume we’ll see it go by on Planet, because odds are very good that we won’t. Ideally, you should add a link to it to your documentation request bug, but at least email us the link!

Join the conversation

We will almost certainly be having discussions about the documentation work you need from us! It’s often helpful for you to be proactive about being engaged in those discussions. It’s always best to get your input, requests, and suggestions sooner rather than later.

  • If your project is large enough, we might start having meetings specifically to discuss its documentation work. This type of meeting is typically short (our Web APIs documentation meeting has never run longer than 20 minutes, for example). We will invite you to attend these, and we’d love to have you, because it’s a great way for you to comment on documentation quality, priorities, and the like.
  • You’re welcome to join us in #mdn, the IRC channel in which we discuss documentation work, if you want to chat with us about specific documentation concerns or questions, or if you want to make a fix or addition yourself but need some advice.

Useful resources

There are a few additional useful resources on MDN that can help to improve the interaction between the writers and the developers for a project:

 Posted by at 12:44 PM
Feb 142014
 

Over the last few days, I’ve provided lots of information about what types of documentation MDN features, how to file a documentation request, and so forth. Now I’d like to share some tips about how to file a documentation request that’s clear and provides all the information the docs team needs in order to do the job promptly and well.

While adding the dev-doc-needed keyword to bugs is a great start (and please do at least that, if nothing else), the best way to ensure your documentation is produced in a timely manner is to file an actual documentation request.

Note: See also my older blog post about the documentation request form; that post is a tad out of date but may also be interesting/useful.

Ask early

The sooner you ask for documentation to be written, the better. Even if you haven’t started to actually write any code, it’s still not too early to file the documentation request! As I’ve mentioned in previous posts, the sooner we know that we may need to write something, the easier it is to nudge it onto our schedule when the time comes. This is both because of easier logistics and because we can ensure we’ve been following the status of your project and often can start research before it’s time to start writing.

As soon as you realize that documentation may need to be written—or updated—file a documentation request!

Write a useful summary

The bug summary should at a minimum mention what APIs or technologies are affected, and ideally will offer some insight into how out of date any existing content is or what Firefox release incorporates the changes. Some good examples:

  • Update FooBar API documentation for Firefox 29 changes
  • Document new interface nsISuperBar added in Gecko 33
  • Document that document.meh method deprecated in Gecko 30, removed in Gecko 31
  • Note in docs that WebSnickerdoodle support brought into line with WebKit implementation in Gecko 28
  • Docs for WebPudding say it’s unsupported in Blink but it is starting in Blink 42

Some bad examples:

  • Docs for WebGL suck
  • Update all docs for Gecko 42
  • Add documentation for <some word that doesn’t match the name of any spec/technology mentioned anywhere on the Web>

Be sure to use the right names of technologies. Don’t use your nickname for a technology; use the name used in the specification!

Where are existing docs?

If you know where the existing documentation for the material that needs updating is, include that information. Obviously, if you don’t know, we won’t make you hunt it down, but if you’re already looking at it and shaking your head going, “Boy, this is lame,” include the URL in your request!

This information goes in the “Page to Update” field on the doc request form.

Who knows the truth?

The next important bit of information to give us: the name and contact information for the person or people that can answer any questions the writing team has about the technology or API that needs documentation work. If we don’t have to hunt down the smartest person around, we save everyone time, and the end result is better across the board.

Put this information in the “Technical Contact” field on the doc request form. You may actually put as many people there as you wish, and this field does autocomplete just like the CC field in Bugzilla, using Bugzilla user information.

When does this change take effect?

If you know when the change will take effect (for Firefox/Gecko related changes, or for implementing open Web APIs in Firefox), include that information. Letting us know when it will land is a big help in terms of scheduling and in terms of knowing what to say in the compatibility table. This goes in the “Gecko Version” field in the doc request form; leave it “unspecified” if you don’t know the answer, or if it’s not relevant.

If you don’t provide these details, we’ll ask for it when the time comes, but if you already know the answer, please do provide as much of this as you can!

On a related note, providing links to the development bug which, upon closing, means the feature will be available in Firefox nightly builds is a huge help to us! Put this in the “Development Bug” field on the doc request form.

Be thorough!

Provide lots of details! There’s a lot of other information that can be useful, and the more you can tell us, the better. Some examples of details you can provide:

  • A brief explanation of what’s wrong (for problems with existing documentation), or what needs to be written.
  • A link to the specification and/or design documents or wikimo pages for the feature.
  • Relevant IRC channels in which the technology is discussed (for example, if it’s a gaming API, you might remind the potential writer to ask about it in #games).
  • Links to blog posts that the dev team(s) have written about the feature/technology/API. These are a great source of information for us!
  • Link(s) to the source code implementing the feature/technology/API.
  • Link(s) to any tests or example code the dev team has written. We use these to help understand how the API is used in practice, and often swipe code snippets for our on-wiki examples from these.
  • Target audience: does this technology/API impact open Web developers? App developers? Both? Only Gecko-internals developers? Add-on developers? Some other group we haven’t previously imagined? Green-skinned aliens? Tortoises?

Wrap-up

I hope this information is useful to help you produce better documentation requests. Not just that, but I hope it gives you added insights into the kinds of things we on the documentation team have to consider when scheduling, planning, and producing documentation and documentation updates.

The more information you give us, the faster we can turn around your request, and the less we’ll have to bug you (or anyone else) to get there.

We know Mozillians love good documentation: hopefully you can help us make more great documentation faster.

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

Conclusion

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