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

This site uses Akismet to reduce spam. Learn how your comment data is processed.