Mar 292014
 

There’s been something of an uproar over Brendan Eich’s promotion to the role of CEO of Mozilla Corporation due to the fact that many years ago, he donated money to support Proposition 8 in California. I’m not going to link to any of the blog posts, tweets, or news stories about this, since I don’t really want to give more traffic to rumormongers, especially since a lot of the stories are mostly speculation.

Since I work for Mozilla, I obviously have opinions on this. I’m going to share them, but first I’m going to be sure to point out what I’m not:

  • I’ve never reported to Brendan either directly or indirectly.
  • I’m not gay, so his opinions in the area don’t directly affect me.

With that out of the way, let me say this: in the more than eight years I’ve worked at Mozilla, I’ve never known Brendan to treat anyone differently based on their gender, sexual orientation, color, religion, eye color, height, weight, or anything else (sorry for being slightly flippant there; it’s how I handle this stuff).

I felt then, and feel now, that Prop 8 is a mistake, is unconstitutional, and is a moral catastrophe. Freedom to marry the consenting adult of your dreams is a core human right and should be protected as such. Now with my feelings on the matter exposed, let’s press on.

While I, too, would like him to make a statement clarifying things further, I also don’t think it’s any of my business. As long as Brendan’s feelings don’t impact his work functions, I honestly don’t care what he thinks. As far as I can tell, all he cares about is whether or not you can deliver the goods when you’re working on the project. That’s all that matters to me.

He can be cranky and dismissive at times when he thinks you’re wrong (or less right than he is), but everyone can be that way (I know I can). Whatever his personal feelings are on gay marriage (or homosexuality in general, or anything else), Brendan is a brilliant developer and manager, a great leader, and an avid supporter of open source software and of the free and open Web. In those respects, he’s the best possible person for the job of CEO of Mozilla.

Mozillians are a diverse community. Brendan knows that; he’s known that since he first helped create Mozilla a decade and a half ago. He’s never once been involved in controversy related to that diversity; becoming CEO doesn’t, I think, make him any more likely to be so.

Let’s give him the benefit of the doubt, and get back to rockin’ the open Web.

 Posted by at 4:04 AM
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 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
Dec 092013
 

Today we launched the new design for the Mozilla Developer Network Web site. We’ve been working on this for a long time, with discussions starting as much as a year ago, and actual coding starting this past summer. It was a huge effort involving a ton of brilliant people, and I’m thrilled with the results! Not only is the new design more attractive, but it has a number of entirely new features that will help you find what you want—and read it—more easily, and in more places, than ever before.

Updated home page

The new home page has a completely revamped organization, with a large search box front and center. Below that are links to key areas of the MDN Web site, including much of our most-used documentation, such as the JavaScript, CSS, and HTML docs, content about Firefox OS and developer tools, and the brand-new Mozilla Developer Program, whose goal is to help Web developers learn more and more quickly.

MDN home page screenshot

Zoning in

You may notice the new concept we call “zones” in the screenshot above. A “zone” is a new concept we’ve added, wherein we can construct a special topic area that can accumulate documentation and samples from across MDN to cover that topic. For example, the Firefox OS zone provides documentation about Firefox OS, which involves not only Firefox OS-specific content, but information about HTML, CSS, and so forth.

Screenshot of the Firefox OS zone landing page

Here you see our new zone navigation bar along the left side of the screen, promotional boxes for specific content, and lists of key articles.

Search and ye shall find

Search has been significantly improved; we now have an on-site search powered by Elastic Search rather than using Google, which lets us customize the search in useful ways. One particularly helpful feature is the addition of search filters. Once you’ve done a search, you can narrow the search further by using these filters. For example, here’s a search for “window element”:

Screenshot of search resultsWell. 5186 results is a lot. You can use our new search filters, though, to narrow those results down a bit. You can choose to restrict your search to one or more topic areas, types of document, and/or skill level. Let’s look for articles specifically about the DOM:

Screenshot of search resultsIt’s worth noting here that these filters rely on content being tagged properly, and much of our content is still in the process of being tagged (especially regarding skill level). This is something we can always use help with, so please drop into #mdn on IRC if you’re interested in helping with this quick and easy way to help improve our search quality!

Responsive design

An area in which MDN was sorely lacking in the past was responsive design. This is the concept of designing content to adapt to the device on which it’s being used. The new MDN design makes key adjustments to its layout based on the size of your screen.

 Screenshot of the Firefox zone landing page in "desktop" view.  Screenshot of the Firefox zone landing page in "small desktop" view. Screenshot of the Firefox zone landing page in "mobile" view.
Here’s the Firefox zone’s landing page in standard “desktop” mode. This is what you’ll see browsing to it in a typical desktop browser environment. Here’s what the same page looks like in “small desktop” mode. This is what the page looks like when your browser window is smaller, such as when viewing on a netbook. And here’s the same page in “mobile” view. The page’s layout is adjusted to be friendlier on a mobile device.

Each view mode rearranges the layout, and in some cases removes less important page elements, to improve the page’s utility in that environment.

Quicklinks

The last new feature I’ll point out (although not the last improvement by a long shot!) is the new quicklink feature. We now have the ability to add a collection of quicklinks to pages; this can be done manually by building the list while editing the page, or by using macros.

Here’s a screenshot of the quicklinks area on the page for the CSS background property:

Quicklinks in the CSS reference.

The quicklinks in the CSS reference provide fast access to related properties; when looking at a background-related property, as seen above, you get quick access to all of the background-related properties at once.

There’s also an expandable “CSS Reference” section. Clicking it gives you an alphabetical list of all of the CSS reference pages:

CSS reference page with expanded links to other pages in the reference.

As you see, this lets you quickly navigate through the entire CSS reference without having to backtrack to the CSS landing page. I think this will come as an enormous relief to a lot of MDN users!

To top it off, if you want to have more room for content and don’t need the quicklinks, you can hide them by simply clicking the “Hide sidebar” button at the top of the left column; this results in something like the following:

CSS reference page with the left sidebar closed.The quicklinks feature is rapidly becoming my favorite feature of this new MDN look-and-feel. Not all of our content is making full use of it yet, but we’re rapidly expanding its use. It makes navigating content so much easier, and is easy to work with as a content creator on MDN, too.

Next steps

Our development team and the design and UX teams did a fantastic job building this platform, and our community of writers threw in their share as well: between testing the changes to providing feedback, not to mention contributing and updating enormous amounts of documentation to take advantage of new features and to look right in the new design, I’m enormously proud of everyone involved.

There’s plenty left to do. There are new platform features yet to be built, and the content always needs more work. If you’d like to help, drop into #mdn to talk about content or #mdndev to talk about helping with the platform itself. And feel free to file bugs with your suggestions and input.

See you online!

 Posted by at 3:12 PM
Oct 252013
 

It’s common for the teams working on parts of the various Mozilla projects to have periodic work weeks or in-person meetups, wherein the teams travel from all over the world to sit in one place and work together or talk for a few days. These are a great way to sync up, bond, and exchange information face-to-face.

There’s a lot of information to be gained at these events. More importantly, perhaps, they’re a great way for people to meet and find out who knows what about which topics. As such, there’s a lot of potential value in having a representative of the MDN writing team attend your work week. By having a writer attend, you can share with them your concerns about the quality or state of the documentation, share valuable insights about how the code works, or even simply guide the writer to where all the best design notes and discussions are archived.

As such, we’d really appreciate being looped in if you have a work week planned. We can’t necessarily send someone to every work week every team has, but we’d sure like to try to at least drop in for a day or two to the ones we can get to.

In addition to our writing team gathering useful information, we can provide useful information to your team, such as:

  • Guidance on how to get your project’s changes into the pipeline for developer documentation work.
  • Training on how your development team can contribute to the documentation (you don’t have to write great docs; just giving us the basics can reduce the time it takes to build great docs by an enormous percentage).
  • We can help you find docs for related technologies that already exist.
  • We can offer insights into ways your APIs could behave more consistently with existing APIs when consistency might be helpful. Since we document a lot of APIs, we can have great ideas in this area.

Whenever your team schedules a work week, please feel free to email me and ask if we could send a writer to join you. Like I mentioned before, we might not always be able to do so, but we will try to when it’s possible and makes sense to do so.

 Posted by at 11:44 AM
Jun 212013
 

That’s right! Our monthly doc sprint is upon us once again! This weekend, we’ll be hanging out in the #devmo channel on Mozilla IRC and writing away. Our suggested topic this month is Web device APIs.

In addition, there’s a local meetup in the Paris Mozilla office! If you’ll be in Paris and would like to drop in and participate, visit the meetup’s Lanyrd page and let everyone know you’ll be there!

These doc sprints are a great opportunity for you to get your feet wet if you’re not a “real” writer. There are lots of friendly contributors around who can help you out, and there are plenty of things to do, including some that don’t require deep writing skills.

Tasks you can help out with during a doc sprint:

If you’re new to MDN, we have documents to help you get started, and an editor guide that provides in-depth documentation about all the things you can do in the MDN editor.

So join us this weekend and get involved! The more the merrier, and we’d love to have you!

 Posted by at 9:35 AM
May 132013
 

A key step in the documentation process is the review. The Mozilla Developer Network (MDN) developer documentation team aspires to perform two types of review on each article on the wiki:

A technical review involves having someone with technical expertise in the article’s subject area read the article and ensure that it’s factually and technically accurate. This means making sure our explanations of the subject matter are right and make sense to the developers, as well as ensuring that any code samples are implemented correctly.

An editorial review is where someone reads the article and corrects any typos, grammatical mistakes, or stylistic or layout problems they can find.

When writing an article (or editing an existing article), there are checkboxes that let you request each of these types of review on your article; indeed, both of these flags are enabled by default for any newly-created page. Yellow banners are displayed at the top of the page to let readers know that these flags are set, as appropriate.

In the past, the only way to remove the review requests (for example, if you’ve read the article and didn’t see any factual errors) was to click the Edit button, scroll to the checkbox for the editorial review, toggle it off, and save the article.

Now there’s a better way!

Now, on pages with one or both of these review flags set, you’ll see a new “Quick review” box at the bottom of the article. This box looks like this:

Screenshot of the quick review box on MDN

The MDN Quick Review box.

All you have to do if you’ve completed a review is to turn on the appropriate checkbox(es) and click “Confirm Reviews.” The review is recorded and you have our gratitude for your help!

If you’d like to actually hunt down and take care of articles in need of review, there’s an easy way to find them:

I’m hopeful that this streamlined approach to reviews will help encourage subject-matter experts to review content, and will help casual users of MDN get involved by reviewing content as well. We have some improvements planned for future updates to MDN that will make this even better, but this is a great start, and I’m grateful to our development team for putting this together!

 Posted by at 1:42 PM