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
Apr 302013

Last night, I got home after another fun and productive MDN documentation sprint; this one was held in Mozilla’s lovely Vancouver office. In addition to Mozilla’s paid writing staff and a few core contributors, we had Mounir Lamouri, a Mozilla platform engineer, on hand to offer technical expertise about web-based device APIs. In addition, two Vancouver-area residents, Aras and Amr, also joined us, making their first contributions to MDN!

The MDN doc sprint team in Vancouver in April 2013.

Photo provided by Florian Scholz.


To top it all off, Vancouver-based content strategy expert Rahel Bailie dropped in to help us do a quick-and-dirty content strategy analysis; it was reassuring to discover that we’re more or less thinking along the right lines and on the right track in that regard.

Both virtual and in-person sprints have their pros and cons. Virtual sprints let people participate from anywhere without the need to travel and leave their normal lives and families behind. But in-person sprints give us the opportunity to have the kinds of conversations that work best when everyone’s in the same room together with a whiteboard. We had several of those conversations during this sprint in addition to documentation writing activities.


Some of the whiteboard discussions we had during this sprint included:

  • We talked about the content and structure for the home page and global navigation of MDN. Expect to see these changes start to happen in the next few weeks!
  • A team met a couple of times to draft and refine a specification for the Localization Dashboard. This has been proposed as a Google Summer of Code project. Whether a student tackles this for GSoC or our own dev team builds it, having a spec is an important step.
  • We had a very long and engaging discussion about MDN’s page types and the elements they need. I will be turning our sketches and notes into a specification proposal this week.
  • We brainstormed ways to improve our involvement in events, whether they’re MDN doc sprints, other Mozilla events, or even external events.
  • We talked about our new process for managing documentation bugs by using the “Developer Documentation” component in Bugzilla along with Scrumbu.gs.

Documentation written

We also had lots of documentation written. I doubt this is an exhaustive list (in fact, I know that it isn’t), but it’s a list of what people specifically noted down that they worked on. Even as an incomplete list, this is a lot of great work. I’d like to thank everyone for their time and effort!

Aras Balali Moghaddam

Aras modified the following pages to make use of live code samples. We’re pretty excited about our live sample system, so getting more of them is always awesome!

Florian Scholz

Eric Shepherd

  • Added a section about media presentation to Firefox OS apps tips and techniques.
  • Updated the docs for nsINavHistoryService to fix bug 703893.
  • Updated the docs for JS_SetGCZeal to note a signature change in Firefox 14, per bug 787723.
  • Created the template APIListAlpha for producing alphabetical lists of subpages as pretty indexes.
  • Started work on building the hierarchy for the new open Web documentation structure, including the Web landing page and the Web APIs page.
 Posted by at 2:18 PM
Apr 252013

Ah, spring! The flowers bloom, the snows melt (usually), and lovers of the Web and of Mozilla are heading to Vancouver, British Columbia to participate in our spring documentation sprint at the Vancouver Mozilla Space.

We’ll be gathering writers and a few developers together to pound out as much great documentation as we can, along with, I’m sure, a few fun evening activities.

If you can join us, feel free to drop in! Or participate virtually by logging into MDN and joining the chat in the #devmo IRC channel. We’ll save a seat for you at the ol’ keyboard.

 Posted by at 8:13 AM
Jan 082013

As a leader of a community-driven documentation project such as that which we have on the Mozilla Developer Network (MDN) wiki, part of my job is to help build that sense of community while at the same time trying to make sure that things get done. This can be a tricky balancing act, especially since I go into things with my own ideas of how I think things should be done, and I’m certainly not always right.

For that reason, it’s sometimes a useful exercise to not get involved in debates and discussions about ideas. At times, I try to simply observe and see where the conversation goes. I let the conversation run its course, then jump in until the discussion reaches one of its typical end points:

  1. A consensus is reached. This happens pretty often, and is the best possible outcome of any conversation. If consensus is reached, I hop in and help to ensure that the idea gets implemented (which sometimes starts a whole new discussion about whose job it is to actually take on the decided-upon course of action).
  2. The conversation peters out with no decision. This is also pretty common. If the conversation fades away, sometimes it’s for the best — whatever was being discussed just isn’t that important, or nobody feels like championing it, so it may as well be left alone for the time being. Other times, I’ll step in and give things a nudge to see if I can get the discussion going again.
  3. The discussion devolves into argument. In our community, at least, this doesn’t happen all that often. When it does, I wade in and try to soothe people’s raw nerves and change the tone of the conversation. I can only think of maybe one or two times this has been necessary, though.

It can be incredibly educational to simply follow along while your community thinks out loud. By keeping your biases out of the way, a lot of great things can happen; often ideas come up that you would never have thought of. In addition, it lets your community members exchange ideas more freely, and can help build their sense of belonging. Certainly it helps them feel more confident that you’re not dictating how things should be done!

Silence isn’t always the best policy, but sometimes it’s a useful tool. Used properly, it can help your community become stronger.

 Posted by at 1:48 PM
Dec 172012

Given our ongoing documentation-needed overload, we’ve decided to look into contracting out some writing work to help catch up our Firefox developer documentation. Basically, we’ve not been able to keep up with our Firefox X for developers documentation (see Firefox 17 for developers, for instance). While stuff gets listed, the list is often not complete, and even where items are put on the list, they’re usually not actually documented.

This is, frankly, embarrassing.

However, the staff writers, and even most of our community of writers, have been very busy with Firefox OS and other documentation, leaving Firefox itself rather strapped for attention. That’s got to change.

So the other day, I talked to Ali (my boss) and we agreed that we should see about contracting someone to go through all of these documents, from Firefox 13 onward, and get them fully up to date, and try to document the technologies and changes as needed.

There are some skills required:

  • You need to be proficient in JavaScript — at least well enough to read code without needing a lot of help, and to throw little snippets together as needed to demonstrate new features.
  • Likewise, you should be competent with HTML and CSS, at least well enough to sort things out without hand-holding.
  • If you have experience reading the IDL that describes DOM interfaces, that’s a big help, but we can help you figure it out (it’s not hard).
  • You should feel comfortable talking to developers by email and in IRC. You’ll have questions and being able to interface with these guys will be a huge help.

You won’t be in this alone, of course. Our existing community of writers hangs out in #devmo on irc.mozilla.org and we’ll be there to offer encouragement, advice, and some help.

If you’re interested, let me know. We haven’t opened up this contract yet, but I’d like to start getting a handle on who might be interested, so I can have a list of possible candidates ready to go once that happens.

This is important work that’s sadly fallen by the wayside due to limited resources and conflicting priorities. Help us make the Firefox developer documentation excellent again!

 Posted by at 1:01 PM
Dec 052012

One of the relatively new features on MDN’s Kuma wiki — and one that’s still a work in progress — is the Revision Dashboard. This dashboard presents you with a list of the most recently changed articles, and lets you review those changes. Although the dashboard isn’t yet linked to from the UI on the MDN wiki, it’s there. We’ll add a link to it soon; we have some UI decisions to make first.

The dashboard page consists of three sections: the filter section, the revision list, and the revision diff.


At the top, there are filtering options.

Screen shot of the filter list

You can choose to filter by locale, if you’re interested only in changes in a given locale. By default, you get all locales, but often you’re only interested in changes in your language (or in English if you’re looking for new stuff to translate). In addition, you can filter to find recent changes for a specific user. You can specify these filters in the URL, as well. For example:

Revision list

The revision list is (surprisingly enough) a list of article revisions. Each row in the list corresponds to one edit to an article. The article’s locale and title are listed, as well as the date of the revision, the username of the person that made the change, and any comment they added when saving the article.

Screenshot of the article list

Clicking on a revision in the list displays the revision’s diff and additional options; with these, you can revert a change (thereby making the version of the article prior to the selected one current), view the page, open the page in the editor, or view the page’s complete history.

Clicking on an article’s title will open that article so you can read it in all its glory. Clicking a username filters the current list to only show changes made by that user.

Revision diff

After you’ve clicked on an article revision, the Revision Diff area shows a diff of the HTML, so you can see what changed in that revision of the article.

Screen shot of the diff area

Viewing the actual article may be handy when reviewing more complex diffs, since it can be hard to gauge what exactly changed when looking at the raw HTML source.

Expect change!

The revision dashboard is undergoing ongoing development, so expect it to look different from time to time. In fact, I’m already seeing mockups of it looking rather different (and better!) than this in several ways. But the core functionality is there. Expect change, but it’ll be great change!

 Posted by at 11:44 AM
Nov 152012

We’re having a virtual — that is, online — MDN documentation sprint from November 30 through December 1! We encourage anyone interested in helping make documentation of and for the open Web to log onto #devmo on irc.mozilla.org and help out. Even if you only have a few minutes, it’s possible to make a huge difference. Indeed, if you’re a Web developer that knows lots of things, you can log in and help answer questions the writers might have. That’s a way you can contribute to MDN content without doing any writing yourself!

Check out the wiki page about this doc sprint and put your name on the list if you plan to participate. There’s even a list of links to suggested topics for work. And you can even contribute by simply adding live samples to existing articles, using our nifty new live sample system!

I hope to see you there! We always have a good time and get lots of great work done to make developing for the open Web easier for everyone!

 Posted by at 7:30 AM
Oct 052012

Note: You may see “documentation process” and think this doesn’t apply to you. You’re almost certainly wrong! If you contribute to the Mozilla project, this almost certainly does apply to you, so please read on!

The short version

Because the rate of development at Mozilla is accelerating faster than the MDN developer documentation team can keep up, it’s time for us to establish a process by which development teams request that the documentation team produce content to cover new features, APIs, and technologies. I have produced a document that outlines a proposed new process by which this will be done, outlining how documentation requests will be handled and prioritized, how we will interact with the developers, and the responsibilities of the writers and the developers in terms of getting the documentation produced.

The long version

Mozilla developers rock. Like… they rock hard. Odds are, if you’re reading this, you’re one of those amazing developers. If you are, you need to understand, first off, that the MDN team knows you’re almost frighteningly good at what you do.

Because of that, we’re totally swamped! With so many amazing new technologies and APIs coming from your keyboards to our to-do lists, we simply can’t keep up. As Mozilla has grown, the amount of material that the developer documentation team needs to produce has skyrocketed. Think about it: we’re documenting one of the most popular Web browsers in the world, a popular e-mail client, open Web standards from HTML through CSS and JavaScript to new technologies like WebAPI, how to write games and apps online, a brand new mobile operating system (Firefox OS), concepts like security, identify management, and the like, and more.

And we do it with a paid staff of four full-time and one part-time writer and a community of contributors who, while amazing, can’t always have the time to document this much cool stuff.

Most large organizations that have technical documentation requirements have a process by which that happens. Mozilla never has; we’ve done our documentation in a very free-form way: a writer sees something needs to be documented and writes about it. A lot of things fall through the cracks because the writers didn’t know they existed, or were ready for documenting.

The time has come for that to change. In an attempt to improve the responsiveness of the documentation team, increase both the quality and the quantity of material we can produce, and help enhance communication between the development and writing teams, I have proposed a documentation process by which development teams will request that writers produce material for their work.

I urge you, if you contribute to Mozilla, to read the proposal and offer your thoughts. I think this will help everyone. Our developers will see their work get properly documented both better and more quickly. Our writers will be able to avoid wasting a lot of time searching for information they shouldn’t have to search for. And our users will get top-notch documentation for the amazing Web of the future.

To offer your feedback, you may either post to the mozilla.dev.mdc mailing list, send me email, or comment on this blog post.

 Posted by at 9:26 AM
Jun 292012

Kuma, the new wiki platform Mozilla is building for the Mozilla Developer Network, is going to be deployed in stages starting on July 5th. As I mentioned yesterday, that day we will direct all attempts to edit the site to the new Kuma site, while viewing will continue (by default) on the current one. Then on the 15th, we will begin directing all traffic to Kuma instead, and it will become the new powerhouse driving developer.mozilla.org.

However, we haven’t really shared a lot of details yet about what features you can expect from the new site. Let me start to fix that! I’ll be blogging over the coming days about the new stuff you’ll see.

First, let me begin by saying that the site will look very familiar if you’re reading it. Indeed, as a typical user, you may not even notice any difference! It’s possible that you may find the occasional glitch, where something hasn’t been updated fully to work correctly on the redesigned site. But we’ll be continuing to work on cleaning those things up.

Indeed, it’s worth keeping in mind that our development team will continue to improve Kuma at a rapid pace over the weeks and months following our launch!

Okay, on to a few of the things that typical users will see.


First off, you may find pages with banners at the top that look like this:

An example of what the review needed boxes look like

That’s because we now have a more formal system of requesting technical and editorial reviews. Whenever a user edits an article, there are checkboxes that they can use when submitting their change to request that someone review the content; this replaces our old system of using “NeedsTechnicalReview” and “NeedsEditorialReview” tags (although those tags have not yet been converted to use the new system).

If you review a page, you can simply turn off the appropriate checkbox on the edit page and save the page. Boom! It’s reviewed!

Contributor list

The only other really obvious change is that at the bottom of the page, you’ll see a list of all the people who have contributed to the article! This little tip-of-the-hat to our community is fantastic! Clicking on the username takes you to their MDN profile page.

More news to come!

Other than these changes, you probably won’t see much difference. There aren’t as many options in the drop-down menus right now, but that will change as our feature set expands. The real changes are going to be visible to our writers and localizers. I’ll be talking about those changes starting tomorrow.

 Posted by at 12:51 PM  Tagged with: