Apr 032017

As of today—April 3, 2017—I’ve been working as a Mozilla staffer for 11 years. Eleven years of documenting the open Web, as well as, at times, certain aspects of the guts of Firefox itself. Eleven years. Wow. I wrote in some detail last year about my history at Mozilla, so I won’t repeat the story here.

I think 2017 is going to be a phenomenal year for the MDN team. We continue to drive forward on making open web documentation that can reach every web developer regardless of skill level. I’m still so excited to be a part of it all!

A little fox that Sophie got me

Last night, my eleven-year-old daughter (born about 10 months before I joined Mozilla) brought home this fox beanie plush for me. I don’t know what prompted her to get it—I don’t think she’s aware of the timing—but I love it! It may or may not actually be a red panda, but it has a very Firefox look to it, and that’s good enough for me.

 Posted by at 7:12 AM
Oct 192016

One of the most underappreciated features of Firefox’s URL bar and its bookmark system is its support for custom keyword searches. These let you create special bookmarks that type a keyword followed by other text, and have that text inserted into a URL identified uniquely by the keyword, then that URL gets loaded. This lets you type, for example, “quote aapl” to get a stock quote on Apple Inc.

You can check out the article I linked to previously (and here, as well, for good measure) for details on how to actually create and use keyword searches. I’m not going to go into details on that here. What I am going to do is share a few keyword searches I’ve configured that I find incredibly useful as a programmer and as a writer on MDN.

For web development

Here are the search keywords I use the most as a web developer.

Keyword Description URL
if Opens an API reference page on MDN given an interface name. https://developer.mozilla.org/en-US/docs/Web/API/%s
elem Opens an HTML element’s reference page on MDN. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/%s
css Opens a CSS reference page on MDN. https://developer.mozilla.org/en-US/docs/Web/CSS/%s
fx Opens the release notes for a given version of Firefox, given its version number. https://developer.mozilla.org/en-US/Firefox/Releases/%s
mdn Searches MDN for the given term(s) using the default filters, which generally limit the search to include only pages most useful to Web developers. https://developer.mozilla.org/en-US/search?q=%s
mdnall Searches MDN for the given term(s) with no filters in place. https://developer.mozilla.org/en-US/search?q=%s&none=none

For documentation work

When I’m writing docs, I actually use the above keywords a lot, too. But I have a few more that I get a lot of use out of, too.

Keyword Description URL
bug Opens the specified bug in Mozilla’s Bugzilla instance, given a bug number. https://bugzilla.mozilla.org/show_bug.cgi?id=%s
bs Searches Bugzilla for the specified term(s). https://bugzilla.mozilla.org/buglist.cgi?quicksearch=%s
dxr Searches the Mozilla source code on DXR for the given term(s). https://dxr.mozilla.org/mozilla-central/search?q=%s
file Looks for files whose name contains the specified text in the Mozilla source tree on DXR. https://dxr.mozilla.org/mozilla-central/search?q=path%3A%s
ident Looks for definitions of the specified identifier (such as a method or class name) in the Mozilla code on DXR. https://dxr.mozilla.org/mozilla-central/search?q=id%3A%s
func Searches for the definition of function(s)/method(s) with the specified name, using DXR. https://dxr.mozilla.org/mozilla-central/search?q=function%3A%s
t Opens the specified MDN KumaScript macro page, given the template/macro name. https://developer.mozilla.org/en-US/docs/Template:%s
wikimo Searches wiki.mozilla.org for the specified term(s). https://wiki.mozilla.org/index.php?search=%s

Obviously, DXR is a font of fantastic information, and I suggest click the “Operators” button at the right end of the search bar there to see a list of the available filters; building search keywords for many of these filters can make your life vastly easier, depending on your specific needs and work habits!

 Posted by at 5:33 PM
Jul 262016

The Web moves pretty fast. Things are constantly changing, and the documentation content on the Mozilla Developer Network (MDN) is constantly changing, too. The pace of change ebbs and flows, and often it can be helpful to know when changes occur. I hear this most from a few categories of people:

  • Firefox developers who work on the code which implements a particular technology. These folks need to know when we’ve made changes to the documentation so they can review our work and be sure we didn’t make any mistakes or leave anything out. They often also like to update the material and keep up on what’s been revised recently.
  • MDN writers and other contributors who want to ensure that content remains correct as changes are made. With so many people making change to some of our content, keeping up and being sure mistakes aren’t made and that style guides are followed is important.
  • Contributors to specifications and members of technology working groups. These are people who have a keen interest in knowing how their specifications are being interpreted and implemented, and in the response to what they’ve designed. The text of our documentation and any code samples, and changes made to them, may be highly informative for them to that end.
  • Spies. Ha! Just kidding. We’re all about being open in the Mozilla community, so spies would be pretty bored watching our content.

There are a few ways to watch content for changes, from the manual to the automated. Let’s take a look at the most basic and immediately useful tool: MDN page and subpage subscriptions.

Subscribing to a page

Animation showing how to subscribe to a single MDN page After logging into your MDN account (creating one if you don’t already have one), make your way to the page you want to subscribe to. Let’s say you want to be sure nobody messes around with the documentation about <marquee> because, honestly, why would anyone need to change that anyway?

Find the Watch button near the top of the MDN page; it’s a drawing of an eye. In the menu that opens when you hover over that icon, you’ll find the option “Subscribe to this page.” Simply click that. From then on, each time someone makes a change to the page, you’ll get an email. We’ll talk about that email in a moment.

First, we need to consider another form of content subscriptions: subtree or sub-article subscriptions.

Subscribing to a subtree of pages


 Posted by at 8:15 PM
Apr 192016

One great thing about watching the future of the Web being planned in the open is that you can see how smart people having open discussions, combined with the occasional sudden realization, epiphany, or unexpected spark of creative genius can make the Web a better place for everyone.

This is something I’m reminded of regularly when I read mailing list discussions about plans to implement new Web APIs or browser features. There are a number of different kinds of discussion that take place on these mailing lists, but the ones that have fascinated me the most lately have been the “Intent to…” threads.

There are three classes of “Intent to…” thread:

  • Intent to implement. This thread begins with an announcement that someone plans to begin work on implementing a new feature. This could be an entire API, or a single new function, or anything in between. It could be a change to how an existing technology behaves, for that matter.
  • Intent to ship. This thread starts with the announcement that a feature or technology which has been implemented, or is in the process of being implemented, will be shipped in a particular upcoming version of the browser.
  • Intent to unship. This thread starts by announcing that a previously shipped feature will be removed in a given release of the software. This usually means rolling back a change that had unexpected consequences.

In each of these cases, discussion and debate may arise. Sometimes the discussion is very short, with a few people agreeing that it’s a good (or bad) idea, and that’s that. Other times, the discussion becomes very lengthy and complicated, with proposals and counter-proposals and debates (and, yes, sometimes arguments) about whether it’s a good idea or how to go about doing it the best way possible.

You know… I just realized that this change could be why the following sites aren’t working on nightly builds… maybe we need to figure out a different way to do this.

This sounds great, but what if we add a parameter to this function so we can make it more useful to a wider variety of content by…

The conversation frequently starts innocuously enough, with general agreement or minor suggestions that might improve the implementation, and then, sometimes, out of nowhere someone points out a devastating and how-the-heck-did-we-miss-that flaw in the design that causes the conversation to shift into a debate about the best way to fix the design. Result: a better design that works for more people with fewer side effects.

These discussions are part of what makes the process of inventing the Web in the open great. Anyone who has an interest can offer a suggestion or insight that might totally change the shape of things to come. And by announcing upcoming changes in threads such as these, developers make it easier than ever to get involved in the design of the Web as a platform.

Mozilla is largely responsible for the design process of the Web being an open one. Before our global community became a force to be reckoned with, development crawled along inside the walls of one or two corporate offices. Now, dozens of companies and millions of people are active participants in the design of the Web and its APIs. It’s a legacy that every Mozillian—past, present, and future—can be very proud of.

 Posted by at 11:00 AM
Apr 032016

Today—April 3, 2016—marks the tenth anniversary of the day I started working at Mozilla as a writer on the Mozilla Developer Center project (now, of course, the Mozilla Developer Network or MDN). This was after being interviewed many (many) times by Mozilla luminaries including Asa Dotzler, Mike Shaver, Deb Richardson, and others, both on the phone and in person after being flown to Mountain View.

Ironically, when I started at Mozilla, I didn’t care a lick about open source. I didn’t even like Firefox. I actually said as much in my interviews in Mountain View. I still got the job.

I dove in in those early days, learning how to create extensions and how to build Firefox, and I had so, so very much fun doing it.

Ironically, for the first year and a half I worked at Mozilla, I had to do my writing work in Safari, because a bug in the Firefox editor prevented me from efficiently using it for in-browser writing like we do on MDN.

Once Deb moved over to another team, I was the lone writer for a time. We didn’t have nearly as many highly-active volunteer contributors as we do today (and I salute you all!), so I almost single-handedly documented Firefox 2.0. One of my proudest moments was when Mitchell called me out by name for my success at having complete (more or less) developer documentation for Firefox 2.0—the first Firefox release to get there before launch.

Over the past ten years, I’ve documented a little of everything. Actually, a lot of everything. I’ve written about extensions, XPCOM interfaces, HTML, a broad swath of APIs, Firefox OS, building Firefox and other Mozilla-based projects, JavaScript, how to embed SpiderMonkey into your own project (I even did so myself in a freeware project for Mac OS X), and many other topics.

As of the moment of this writing, I have submitted 42,711 edits to the MDN wiki in those ten years. I mostly feel good about my work over the last ten years, although the last couple of years have been complicated due to my health problems. I am striving to defeat these problems—or at least battle them to a more comfortable stalemate—and get back to a better level of productivity.

Earlier, I said that when I took the job at Mozilla, I didn’t care about the Web or about Firefox. That’s changed. Completely.

Today, I love my job, and I love the open Web. When I talk to people about my job at Mozilla, I always eventually reach a point at which I’m describing how Mozilla is changing the world for the better by creating and protecting the open Web. We are one of the drivers of the modernization of the world. We help people in disadvantaged regions learn and grow and gain the opportunity to build something using the tools and software we provide. Our standards work helps to ensure that a child in Ghana can write a Web game that she and her friends can play on their phones, yet also share it with people all over the world to play on whatever device they happen to have access to.

The Web can be the world’s greatest unifying power in history if we let it be. I’m proud to be part of one of the main organizations trying to make that happen. Here’s to many more years!

 Posted by at 2:59 PM
Nov 132015

I’m going to highlight a meeting for you today. This is the point where you yawn politely, look at the time, and and try to escape without my noticing. But I see you over there! Get back here. This is important!

Each Thursday, the MDN content team holds its weekly API documentation meeting at 8 AM Pacific time in Mozilla’s Open the DevEngage Vidyo room. This meeting is for discussions about ongoing and upcoming work on documentation for all Web APIs. This includes the classic DOM as well as all newer APIs, from Ambient Light to Speech Synthesis and beyond. It even includes Firefox OS-specific APIs. We don’t even discriminate against non-standard APIs, as long as they’re exposed to browser content.

That’s a lot of stuff to cover! Everything needs to be understood, written about, sample code located or created (and tested!), and all tied together and reviewed until it makes sense and is as accurate as we can make it.

That’s why we have been holding these meetings in collaboration with the API development team for a long. A few months ago, the technical evangelism team also started sending a representative to each meeting. This tripartite meeting lets each team share recent accomplishments and what they’ll be doing next. This has multiple benefits:

  • The writers learn what new technologies are being implemented, what improvements are in the works, and when things are likely to ship. We also learn when special events are coming that would benefit from having documentation ready.
  • The technical evangelists get details on what new APIs are coming up, and can discuss plans for spreading the word with the developers creating the APIs and the writers documenting them, to coordinate plans and schedules.
  • The technical evangelists can relay user sentiment information in a more personal way to both the development teams and the writers; this kind of feedback is incredibly helpful!
  • The development team can let the writers and evangelists know what the status is on current API work, and we can discuss this status in a team setting instead of only reading about it in a formal note or bug comments.
  • The developers can share information about what problem points they see or expect to exist in understanding and working with technologies, in order to help guide future work in samples, demos, and documentation.

There are intangible benefits, too. Over the two-plus years we’ve been holding this weekly meeting, we’ve developed an increasingly close working relationship between the developer documentation and the API engineering teams. This has enormous benefits not just for these two teams, but for the Web we serve.

If you have a passion for creating APIs for the Web or for teaching others how to use them, please consider joining our meeting. Even if you only drop in once in a while, you’ll find it a great way to stay informed and to help guide the future of our content and evangelism efforts.

 Posted by at 6:07 PM
Nov 032015

It’s been a while since I wrote anything on my blog about technology or the Web (indeed, the last several posts I’ve written have been my 5-word movie reviews. While fun, these aren’t very informative to the primary audience of my blog: you, the (probably) Web developer, genius type.

A lot has changed in the last few months. We’ve got so many exciting new technologies and APIs to play with. Not to mention ECMAScript 6 (a.k.a. ECMAScript 2015, a.k.a. the latest version of JavaScript). In ES6, the big new toys, for me, are Promises and arrow functions. Both take some getting used to, but once you do, they make a huge difference in code readability and despite feeling alien and weird to my old procedural programming brain, they still make code just plain better.

Add to that all the amazing new APIs, including WebRTC, Web Notifications, Service Workers, the Push API, and so much more, and my mind boggles at the immense power of the Web in this day and age.

I was in college when the Web first exploded into existence. Back then, it was mostly a thing students and researchers played with, but I already knew it was going to change the world. And it has.

I’ll try to get back into the habit of blogging more regularly; there’s far too much exciting stuff to talk about to let my blog stay idle any longer.

 Posted by at 11:19 AM
Apr 032015

It was nine years ago today that I joined Mozilla as a senior technical writer. I was hired by Mike Shaver and Deb Richardson to help try to keep up with the pace of progress and to work on organizing and cleaning up older content as well. I actually started working the last few days of March, but my first official day (that is to say, the first day I was paid for) was April 3, 2006.

My daughter wasn’t even a year old yet then. Now she’s almost finished with the fourth grade.

We were deep into the documentation process for Firefox 2.0 back then (not to mention trying to finish bits and pieces of critical documentation for Firefox 1.5, which shipped months earlier). It shipped a few months after my joining the company, and was the first release we generally felt was completely documented (for a slightly flexible definition of “completely”).

A lot has changed over those nine years. Back then, Deb and I were the entire writing staff; we had some contributors but not nearly enough. Then Deb moved onward and upward into other awesome things and it was just me for a while. But eventually we started hiring more writers, thankfully, and we wound up with the kick-ass staff we have today. And as we built up our staff, we learned more about community building, and our community of volunteer writers and contributors has grown at an ever-increasing rate.

This is far and away the longest I’ve spent at any job. It’s a great deal of fun, even when I’m stressing out over all the stuff I wish I had time to write about but don’t. Making the world a better place to be a Web developer is a rewarding career path, and I’m glad Dave Miller steered me into the Mozilla community.

 Posted by at 11:00 AM
Sep 262014

I can’t believe another week has already gone by. This is that time of the year where time starts to scream along toward the holidays at a frantic pace.

What I did this week

  • I’ve continued working heavily on the server-side sample component system
    • Implemented the startup script support, so that each sample component can start background services and the like as needed.
    • Planned and started implementation work on support for allocating ports each sample needs.
    • Designed tear-down process.
  • Created a new “download-desc” class for use on the Firefox landing page on MDN. This page offers download links for all Firefox channels, and this class is used to correct a visual glitch. The class has not as yet been placed into production on the main server though. See this bug to track landing of this class.
  • Updated the MDN administrators’ guide to include information on the new process for deploying changes to site CSS now that the old CustomCSS macro has been terminated on production.
  • Cleaned up Signing Mozilla apps for Mac OS X.
  • Created Using the Mozilla build VM, based heavily on Tim Taubert’s blog post and linked to it from appropriate landing pages.
  • Copy-edited and revised the Web Bluetooth API page.
  • Deleted a crufty page from the Window API.
  • Meetings about API documentation updates and more.

Wrap up

That’s a short-looking list but a lot of time went into many of the things on that list; between coding and research for the server-side component service and experiments with the excellent build VM (I did in fact download it and use it almost immediately to build a working Nightly), I had a lot to do!

My work continues to be fun and exciting, not to mention outright fascinating. I’m looking forward to more, next week.

 Posted by at 5:25 PM
Sep 222014

I’ve been working on getting a first usable version of my new server-side sample server project (which remains unnamed as yet — let me know if you have ideas) up and running. The goals of this project are to allow MDN to host samples that require a server side component (for example, examples of how to do XMLHttpRequest or WebSockets), and to provide a place to host samples that require the ability to do things that we don’t allow in an <iframe> on MDN itself. This work is going really well and I think I’ll have something to show off in the next few days.

What I did this week

  • Caught up on bugmail and other messages that came in while I was out after my hospital stay.
  • Played with JSMESS a bit to see extreme uses of some of our new technologies in action.
  • Did some copy-editing work.
  • Wrote up a document for my own reference about the manifest format and architecture for the sample server.
  • Got most of the code for processing the manifests for the sample server modules and running their startup scripts written. It doesn’t quite work yet, but I’m close.
  • Filed a bug about implementing a drawing tool within MDN for creating diagrams and the like in-site. Pointed to draw.io as an example of a possible way to do it. Also created a developer project page for this proposal.
  • Exchanged email with Piotr about the editor revamp. It’s making good progress.

Wrap up

I’m really, really excited about the sample server work. With this up and running (hopefully soon), we’ll be able to create examples for technologies we were never able to properly demonstrate in the past. It’s been a long time coming. It’s also been a fun, fun project!


 Posted by at 12:16 PM