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 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
Sep 152014

You may notice that I’m posting this on Monday instead of Friday (despite what the title says). Last week was a bit of a mess; I had a little bit of a surprise on Wednesday that involved my being taken to the hospital by ambulance (no lights and siren — it wasn’t that big a surprise), and that kept me away from work for most of the rest of the week.

I’m feeling fine now, although there’s some follow-up medical testing to do to check things out.

Anyway! On to the important stuff!

What I did this week

  • Deleted an inappropriate article from the MDN inbox and emailed the author explaining why.
  • Succeeded in first deployment of a test of my new live sample server-side component server project.
  • Discovered the native GitHub application for Mac, which makes my life enormously easier.
  • Added more information to the comments on bug 1063580, about how shift-refreshing of macros no longer lets you pick up changes to macros and submacros.
  • Updated “How to create an MDN account” to consider that you can use either Persona or GitHub now as your authentication service. This fixed bug 1049972.
  • Added the dev-doc-needed keyword to bug 1064843, which is about implementing ::backdrop in Gecko.
  • Updated the draft of the State of MDN for August to include everything I could think of, so Ali can get it posted (which has happened!).
  • Created the soapbox message to appear at the top of MDN pages about the net neutrality petition. This has since been removed once again, since the event in question has passed. This resolved bug 1060483.
  • Finished debugging the SubpageMenuByCategories and MakeColumnsForDL macros. The former is new and the latter has been updated to support multiple <dl> lists with interspersed headings.

Meetings attended this week


  • #mdndev planning meeting.
  • #mdndev triage meeting.

Last week started off on a high note, with some very productive activity, and then went sideways on Wednesday and never really recovered. I have high hopes for this week though!

 Posted by at 8:26 AM
Sep 052014

First, a personal note:

Holy frickity-frak! It’s September!?

Okay, back to business. My work this week was all over the place. Got tons done but, of course, not what I meant to do. That said, I did actually make progress on the stuff I’d planned to do this week, so that’s something, anyway.

I love this job. The fact that I start my week expecting one awesome thing, and find myself doing two totally different awesome things instead, is pretty freaking cool.

What I did this week

  • Filed bug 1061624 about the new page editing window lacking a link to the Tagging Guide next to the tag edit area.
  • Followed up on some tweets reporting problems with MDN content; made sure the people working on that material knew about the issues at hand, and shared reassurances that we’re on the problem.
  • Tweaked the Toolbox page to mention where full-page screenshots are captured in both locations where the feature is described (instead of just the first place). Also added additional tags to the page.
  • Had a lot of discussions, both by video and by email and IRC, about planning and procedures for documentation work. A new effort is underway to come up with a standard process.
  • Submitted my proposal for changes to our documentation process to Ali, who will be collating this input from all the staff writers and producing a full proposal.
  • Checked the MDN Inbox: it was empty.
  • Experimentation with existing WebRTC examples.
  • Moved some WebRTC content to its new home on MDN.
  • Filed bug 1062538, which suggests that there be a way to close the expanded title/TOC editor on MDN, once it’s been expanded.
  • Fixed the parent page links for the older WebAPI docs; somehow they all believed their parent to be in the Polish part of MDN.
  • Corrected grammar in the article about HTMLMediaElement, and updated the page’s tags.
  • Filed a bug about search behavior in the MDN header, but it was a duplicate.
  • Discovered a privacy issue bug and filed it. A fix is already forthcoming.
  • bz told me that previewing changes to docs in the API reference results in an internal service error; I did some experimenting, then filed bug 1062856 for him. I also pinged mdn-drivers since it seems potentially serious.
  • Discovered an extant, known bug in media streaming which prevents me from determining the dimensions of the video correctly from script. This is breaking many samples for WebRTC.
  • Went through all pages with KumaScript errors (there were only 10). All but one were fixed with a shift-refresh. The last one had a typo in a macro call and worked fine after I fixed the error.
  • Expanded on Florian’s Glossary entry about endianness by adding info on common platforms and processors for each endianness.
  • Filed bug 1063560 about search results claiming to be for English only when your search was for locale=*.
  • Discovered and filed bug 1063582 about MDN edits not showing up until you refresh after saving. This had been fixed at one point but has broken again very recently.
  • Started designing a service to run on Mozilla’s PaaS platform to host the server side of MDN samples. My plan is nifty and I’ll share more about it when I’m done putting rough drafts together.
  • Extended discussions with MDN dev team about various issues and bugs.
  • Helped with the debugging of a Firefox bug I filed earlier in the week.

Meetings attended this week


  • #mdndev planning meeting
  • 1:1 with Jean-Yves


  • 1:1 meeting with Ali


  • Writers’ staff meeting
  • Compatibility Data monthly meeting


  • #mdndev weekly review meeting
  • Web API documentation meeting; only myself, Jean-Yves, and Florian attended but it was still a viable conversation.

A good, productive week, even if it didn’t involve the stuff I expected to do. That may be my motto: I did a lot of things I didn’t expect to do.

 Posted by at 5:17 PM
Aug 292014

This week, my WebRTC research continued; I spent a lot of time watching videos of presentations, pausing every few seconds to take notes, and rewinding often to be sure I got things right. It was interesting but very, very time-consuming!

I got a lot accomplished this week, although not any actual code on samples like I’d planned to. However, the pages on which the smaller samples will go are starting to come together, between bits of actual content on MDN and my extensive notes and outline. So that’s good.

I’m looking forward to this three-day Labor Day holiday here in the States. I’ll be back at it on Tuesday!

What I did this week?

  • Copy-edited the Validator glossary entry.
  • Copy-edited and cleaned up the Learning area page Write a simple page in HTML.
  • Created an initial stub documentation project plan page for updating the HTML element interface reference docs.
  • Turned into a redirect to the right place.
  • Read a great deal about WebRTC.
  • Watched many videos about WebRTC, pausing a lot to take copious notes.
  • Built an outline of all the topics I want to be sure to cover. I’m sure this will continue to grow for a while yet.
  • Gathered notes and built agendas for the MDN community meeting and the Web APIs documentation meeting.
  • Updated the WebRTC doc plan with new information based on my initial notes.
  • Offered more input on a bug recommending that we try to add code to prevent people from using the style attribute or any undefined classes.
  • Filed bug 1060395 asking for a way to find the pages describing the individual methods and properties of an interface in the Web API reference
  • Fixed bug 1058814 about hard-to-read buttons by correcting the styles used by a macro.
  • Dealt with expense reports.
  • Started very initial work on WebRTC doc tree construction, preparing to reshuffle and clean up the existing, somewhat old, pages, and to add lots of new stuff.
  • Started work on trying to figure out how to make the SubpageMenuByCategories macro not lose headers; it’s calling through to MakeColumnsForDL, which specifically only works for a straight-up <dl>. Fixing this to work correctly will be my first task on Tuesday.

Meetings attended this week


  • MDN bug triage meeting
  • #mdndev planning meeting


  • Developer Relations weekly meeting.
  • 1:1 with Teoli. This went on for an hour instead of the usual 30 minutes, due to the enormous amount of Big Stuff we discussed.


  • MDN community meeting


A pretty good week all in all!

 Posted by at 10:38 PM
Aug 222014

This week looks slower than usual when you look at this list, but the week involved a lot of research.

What I did this week

  • Reviewed and made (very) minor tweaks to Chris Mills’s doc plan for the Gaia web components and QA documentation.
  • Created an initial stub of a page for the canvas documentation plan.
  • Spent the weekend and a bit of Monday getting my broken server, including this blog, back up and running after a not-entirely-successful (at first) upgrade of the server from OS X 10.6.8 Server to 10.9.4. But most things are working now. I’ll get the rest fixed up over the next few days.
  • Pursued the MDN inbox project, trying to wrap it up.
    • Asked for feedback on the current state of things.
    • Added a subtle background color to the background of pages in the Inbox.
  • Started discussions on dev-mdc and staff mailing list about the documentation process; we’re going to get this thing straightened up and organized.
  • Filed bug 1056026 proposing that the Firefox_for_developers macro be updated to list both newer and older versions of Firefox.
  • Redirected some obsolete pages to their newer, replacement, content in the MDN meta-documentation.
  • Created a Hacker News account and upvoted a post about Hacks on canuckistani’s request.
  • Updated the MDN Administration Guide.
  • Installed various packages and add-ons on my Mac and server in preparation for testing WebRTC code.
  • Forked several WebRTC projects from GitHub to experiment with.
  • Found (after a surprisingly length search) a micro-USB cable so I could charge and update my Geeksphone Peak to Firefox OS 2.0’s latest nightly build.
  • Re-established contact with Piotr at CKSource about continuing work to get our editor updated and improved.
  • Removed a mess of junk from a page in pt-BR; looks like someone used an editor that added a bunch of extra <span>s.
  • Successfully tested a WebRTC connection between my Firefox OS phone and my iMac, using my Mac mini as server. Now I should be ready to start writing code of my own, now that I know it all works!
  • Filed bug 1057546: we should IMHO strip HTML tags that aren’t part of a string from within a macro call; this would prevent unfortunate errors.
  • Filed bug 1057547 proposing that the editor be updated to detect uses of the style attribute and of undefined classes, and present warnings to the user when they do so.
  • Fixed a page that was incorrectly translated in place, and emailed the contributor a reminder to be careful in the future.

Meetings attended this week


  • MDN dev team meeting on security and improved processes to prevent problems like the email address disclosure we just had happen.
  • MDN developer triage meeting.


  • Developer Engagement weekly meeting.
  • 1:1 with Jean-Yves Perrier.


  • 1:1 with Ali.


  • Writers’ staff meeting.


  • #mdndev weekly review meeting.
  • MDN bug swat meeting.
  • Web API documentation meeting.

So… it was a wildly varied day today. But I got a lot of interesting things done.

 Posted by at 6:16 PM
Aug 162014

I’m quite satisfied with how well the past week has gone. It’s been incredibly productive despite a few distractions and a great many meetings. Here’s my report on what I’ve been doing, and what I will be doing in the near future.

What I’m up to

I’ve been busy optimizing my own work processes, as well as setting up information so others know what needs to be done as well. I’ve also done a lot of copy-editing and organizational work in content, and have been touching up stuff ranging from the MDN inbox to the Learning Area to doc plans. It’s been a wonderfully productive week, and it feels good to be getting back into the swing of things.

What’s up next

Next week, I intend to dive into WebRTC, and to start putting together sample code so I can begin work on writing guides to working with WebRTC. It’s going to be really exciting!

As usual, of course, I have a number of other, smaller, tasks I want or need to accomplish, too.

What I did this week

  • Moved the main page on DocShell from the top level of MDN to its proper home, and filed a bug on getting it fully documented.
  • Dealt with infrastructure failures at my office: the air conditioning completely failed (working in a swelteringly hot office is not fun), and I discovered standing water in the restroom. The A/C is now fixed; the water problem has not been figured out yet, although the water has evaporated for now.
  • Helped test the new GitHub login support on the MDN staging server, and filed a few bugs regarding quirks I noticed.
  • Reviewed and had nothing but nice things to say about the new welcome email sent out by MDN to new members.
  • Got involved in the discussion about disabling styled pasting in the MDN editor. I’m opposed to this; I would much rather we solve the problem from the user’s end — contributors should learn to be sure they don’t include crufty styles when they paste into MDN. But ideally we can come up with a solution that doesn’t break existing workflows, punishing people who aren’t making this mistake.
  • Moved the page Write a new entry in the Glossary to the right place; it had accidentally been given an obsolete URL due to a couple of MDN bugs. Reviewed and copy-edited the content.
  • Filed a bug for a feature suggested by biraj: content from one page on MDN that’s presented inside another page should be reflected in the displayed contributor list. I don’t know how likely this is to be addressed (it certainly won’t happen soon). It’s a big project and there are many unanswered questions.
  • Copy-edited the new Glossary entry for the term “i18n“.
  • Added the word “Glossary” to the list of tags that MDN offers auto-completion for.
  • Followed-up on a bug asking me to write some copy for the Github login experience.
  • Did some tidying up of the MDN style guide, including moving Chris Mills’ excellent new section on our policies on gender-neutral terminology to be among the language and grammar topics rather than in the markup and wiki usage topics area.
  • Minor changes to the Learning Area page on CSS. This page needs a lot of work still but I saw low-hanging fruit.
  • Converted the Learning Area into a zone. Its landing page needs finishing, but this is a nice step.
  • Finished an extensive review and copy-edit of the Learning Area page Write an article to help learn about the web.
  • Removed a page that was actually just a set of Firefox problem reports, and emailed the author information about how to properly report issues.
  • Found an MDN “Linking Guide” lurking in a dead part of the site, and moved it into the MDN user guide, with major updates and copy-edits.
  • Updated the MDN user guide’s landing page to use the LandingPageListSubpages macro, so it looks a little better.
  • Adapted Luke’s screenshot/diagram about how to enable a page subscription on MDN into a new page in the MDN how-to guide.
  • Tweaks to the Inbox page in preparation for expanding its visibility.
  • Integrated the first round of feedback into the WebGL documentation plan.
  • Updated my Geeksphone Peak to Firefox OS 2.0 nightly for use in upcoming WebRTC sample code tests.
  • Filed a bug about saying “Android not supported” on Firefox OS 2.0’s browser.
  • Pinged developers about reviewing the WebGL documentation plan.
  • Created several new basic (that is, mostly empty) MDN development project plan pages:
  • Copy-edited the Learning Area’s How to contribute to the Learning Area article.
  • Filed a documentation request bug for documenting the NavigatorFeatures (hasFeature/getFeature) API. This API is low-priority privileged API, documentation-wise.
  • Added notes to a couple of pages in the MDN contributor guide about being careful when pasting, to avoid pasting unwanted styles and classes into MDN.
  • Created the DocPlanHelpUs macro, which inserts text inviting participation in a project and describing how to get started. Added it to the appropriate place in all extant doc plans.
  • Took some notes, sent some emails, and added links to the project planning page for the on-site messaging project.
  • Added a link to the MDN contributor guide to the footer of messages on the dev-mdc mailing list, and tweaked my email address on the moderator email list names.

Meetings attended this week


  • #mdndev bug triage
  • MDN development planning


  •  1:1 meeting with Jean-Yves


  • MDN Community meeting
  • 1:1 meeting with Ali


As you see, it was an intensely busy week! I’ve started moving into using OmniFocus to track what needs to be done and by when and I think it’s going to help, but we will see how it plays out over time. I have a history of not doing well at keeping up with my organizational systems, as you’ve possibly noted if you read my posts over history about my various attempts to get organized.

At any rate, it’s been a good week, and I can’t wait to get more done!


 Posted by at 12:07 AM