Jun 142014
 

I’m happy with how my talk at the Open Help conference went this morning. I gave a talk about how Mozilla builds, fosters, and provides useful information to our documentation community. I enjoyed giving it, and the questions were good ones.

I saw a lot of note-taking and nodding heads, and the discussions over the rest of the day definitely gave me the sense that people appreciated my thoughts on documentation community-building and processes. I hope there will be video available at some point; certainly it was recorded.

Our documentation status pages and other ways we present data about tasks that need to be performed really got a lot of attention, and Florian’s graph of our contributor growth really opened some eyes — especially when I pointed to the sharp uptick since we deployed our in-house grown, open source, Kuma documentation platform.

Also, I think our development team will be pleased that I heard a lot of “I wish we were using Kuma for our docs” today, and at least one person saying they’re going to look at setting up to try building it themselves.

Three or four people said that if it were separated from the Mozilla-specific bits, they’d be pushing to switch to Kuma. That made me smile; hopefully they will still feel that way if/when we manage to ever make the platform separate from the MDN-specific parts.

I’m with my people here; it’s really wonderful to just talk about documentation tactics without all the other stuff. It’s a great feeling, especially when it seems you’re able to give your peers ideas to take home and try for themselves.

My slides

View my slides below, or download them as a PDF.

 Posted by at 10:10 PM
Jun 112014
 

I’ll be attending the Open Help Conference & Sprints event this weekend, arriving in Cincinnati on Friday afternoon and returning home on Tuesday morning after the first day of documentation sprinting. Mozilla is a proud sponsor of this event, which features a number of key influencers in the open source documentation arena. The mission: to exchange notes and ideas about how to improve the quality and quantity of good open source documentation, and to hold documentation sprints to get some writing projects done.

I’ll be giving a talk on Saturday morning (at 10 AM—the first presentation of the event) entitled “Help people so they can help you.” I’ll be covering the things the MDN team does to build, foster, and support its growing community of contributors. I’m looking forward to this, even though I’m nowhere near prepared yet. I enjoy sharing ideas about how to create and maintain excellent documentation. It’s my career’s mission, and as a Mozillian, I’m pleased to be able to share. Hopefully, too, I’ll get new ideas this weekend as well!

As an aside, if you have any thoughts on things I should be sure to mention, don’t hesitate to leave a comment or drop me an email!

If you’re going to be at Open Help, or are simply in the Cincinnati area, I hope to run into you!

 Posted by at 9:51 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
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.

Conversations

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.

Filters

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