Oct 262012

We’ve got a fresh update to the Kuma software that powers the MDN wiki for you! There’s not a lot of visible stuff here, but a lot is going on:

  • The “Sort table” option in the contextual menu that appears in the editor when you right-click on a table has returned!
  • The first preview version of our revision dashboard has been implemented. It’s nowhere near finished yet, but it’s a start. Because the current implementation is very low performance, access is currently heavily restricted to a few select people. We’ll open it up to everyone once the performance is in a safer place.
  • The wiki is now configured to use Mozilla’s content delivery network (CDN) to improve performance. Speed should be very noticeably improved now, especially if you’re outside North America.

The revision dashboard is a new feature we’re working on that will provide a one-stop page where you can go to see all the most recent changes to the site. You can see a mock-up for what it will eventually more or less look like:

A mockup of what the revisions dashboard will more or less look like eventually

And here’s what the current preview version actually looks like:

A screenshot of the current build of the revisions dashboard

The appearance is currently extremely rough, and none of the filters or features for actually manipulating the revisions in any way have been put into place yet.

The top area is a list of all of the most recent changes to the site (newest revision first, getting progressively older in each row in the list). Clicking on a change displays the diff for that change below.

This provides a convenient way to quickly review changes to the site.

Over time, this dashboard will offer features for reverting changes, banning users (if you’re an admin), quickly getting to pages to do an edit or view the page’s full history, and so forth. In addition, eventually we will find and use a better diff display that shows you a better look at the page. At any rate, this is very exciting progress, and I promise you’ll get to use this yourself before too long!

 Posted by at 4:02 PM  Tagged with:
Oct 252012

After years of wishing we had a complete reference to events supported by Firefox (both standard events and non-standard ones, including those used just for add-ons), we finally have one! Louis-Rémi Babé has produced the Mozilla event reference! He scoured specifications, existing documentation, and the source tree, hunting down every event and documenting it. At this point, if any are missing, it’s purely an oversight. Please feel free to contribute additions and corrections as needed. In particular, we could really use help building out compatibility tables for each event.

When I first joined Mozilla 6 ½ years ago, one of the first things I noticed was that we had no thorough reference to events. Indeed, even what little documentation we had for events was strewed haphazardly through the docs, such as bits of documentation for certain DOM events being contained within pages about the DOM objects that send them. Over time, occasional abortive attempts were made to unify or at least standardize this content, but not much ever came of it. Finally, Louis-Rémi got on the job late this summer and pounded it out.

There’s likely some clean-up work left to be done, and odds are we could use more examples of how to make use of some of these events. However, the fact that we finally have an easy way to hunt down the right event for the task at hand is a victory for the MDN community and for the broader Web development community.

Well done, Louis-Rémi! Thank you!

 Posted by at 9:12 AM
Oct 112012

Yep! Even though we did a push yesterday, we have another one today! A few things that needed extra testing, or weren’t quite ready yesterday are ready now. There’s a lot of stuff here in preparation for the launch of the first pass of our live sample support! These are exciting times!

  • Fixed a bug that was causing page edits to sometimes create faulty redirects to their parents.
  • Initial work on the live sample view. I will blog separately about this once it’s ready to actually use. This is one of the things I’ve been looking forward to for years!
  • The CSS class names used by the syntax highlighter are better; this is related to the sample view work.
  • All site images have been further optimized (losslessly), thereby reducing size by about 10%.

So progress is progress! We should have the ability to actually use the new live sample features soon!

 Posted by at 5:56 PM  Tagged with:
Oct 102012

We have a new update to the Kuma software that drives the MDN site today! This is an interesting assortment of changes, most of which you probably won’t directly notice, but should improve the site on a general level.

  • MDN now has a sitemap.xml file, which is automatically updated periodically. This should improve SEO, possibly significantly.
  • RSS feeds were being generated based on the wrong timestamp, resulting in spurious entries in the feeds being created whenever anyone force-refreshed a page. Now this won’t happen anymore.
  • The keyboard shortcuts for “save” and “save-and-exit” have been swapped, so that they match what we intended.
  • A lot of back-end work has been done toward implementing page moving. It’s not yet exposed to users, though.
  • The content of the <title> of pages on MDN has been changed slightly to improve legibility.
  • The <ruby>, <rp>, and <rt> elements are now allowed in article contents.
  • The font-variant CSS property is now allowed in article contents.
  • A <dfn> element is now used on the slug box in the editor to provide an explanation of what the term “slug” means; this will help users understand how things are done a little better.
  • Some administrative code has been written to help repair some translated pages which are missing their breadcrumb trails.

There’s a lot of code here. In particular, a ton of work has been done toward implementing page moving. Just because you don’t see it yet doesn’t mean a lot of progress hasn’t been made. This should reach these golden shores soon!

Our development team continues to amaze me. There are some great updates coming soon. Prepare to enjoy some fabulous new features soon!

 Posted by at 2:17 PM  Tagged with:
Oct 082012

For much of the past year, Mozilla has been working along with an astonishing collection of Web superpowers to help create a new resource for Web developers. When you get Mozilla, W3C, Adobe, Facebook, Google, HP, Microsoft, Nokia, and Opera all working together to ensure that the content on a site reflects the realities of the modern open Web, the result is bound to be exciting.

And it is! The new Web Platform Docs site is nowhere near complete yet — this is a huge job! — but it’s off to a great start. All of these organizations have contributed some content, funding, and content to the site, and have vowed to continue to do so going forward. The result, over time, should be the most accurate resource for open Web developers on the planet.

Of course, you may ask, “What does this mean for MDN?”

In the short to medium term, not much. We do encourage our contributors to consider putting their content on both sites (keeping in mind that the licenses are different; we use CC-SA and WPD uses CC-BY). Over the long term, once WPD takes off and is a success, hope to move toward putting all open Web content there, and using MDN solely for Mozilla-specific content. Time will tell.

In the meantime, welcome WPD! I look forward to watching you grow up.

 Posted by at 4:30 PM
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
Oct 042012

It’s rare, when writing documentation, that questions don’t arise. When writing documentation, we try to avoid hassling the engineers with questions, but it’s almost inevitable that we’ll run into something we’re not able to figure out on our own. When that happens, we need to know who to contact with our question.

And, all too often, we have no clue at all who we should reach out to. We’ll ask blindly on IRC and sometimes (but not as often as we’d like) get the answer we seek. Then we’ll ask on mailing lists. Often that’s a dead end. Then we resort to emailing people at random until the answer is found.

There’s a way to make this better. I’ve created a new page on the MDN site on which I’d like to try to build a list of subject-matter experts (SMEs). SME is a lingoistic way to describe a person who’s an expert at a technology to the point that they’re the right person to go to when you have questions about the technology, its implementation, and its usage.

Having this list will save our writing team a lot of time, and will help us produce quality documentation for your technologies more quickly, efficiently, effectively in the future.

Please take a look at the list and fill out any contact information you can, or add new rows to the table if we’re missing technologies (which I’m quite sure we are!).

Thanks in advance from the happy, helpful documentation gnomes of Mozilla!

 Posted by at 2:22 PM
Oct 022012

Yesterday I finally got an answer as to why I’ve had near-constant neck, shoulder, and facial pain for the last several months (and some degree of it for a very long time). A cervical spine MRI shows that I have a condition called cervical spinal stenosis, among other issues.

In the C5-C6 area of my neck, quote:

Uncovertebral spurring with accompanying disc material is present both centrally and laterally. There is significant proximal right neural foraminal narrowing and compression of the right C6 nerve root. Moderate canal stenosis overall with AP dimension of the canal approximately 8 to 9 mm and mild to moderate cord compression. Milder narrowing of the left neural foramen due to spurring and mild compression of the left C6 nerve root.

In the C6-C7 area:

Milder uncovertebral spurring with accompanying disc bulge. Mild canal and neural foraminal narrowing but no cord or nerve root compression.

Basically, some of the nerves in my neck are being compressed by deformity in my spinal column; I also have mild arthritis in my neck.

My neurologist has urged me to have surgery as soon as I can in order to resolve this. The procedure is fairly commonplace, so it shouldn’t be too big a deal. Other than it may conflict with my plans to travel to the Caribbean in November. A lot depends on exactly what procedure is needed (which will determine how long my recovery time will be) and how long after my first meeting with the surgeon I’m able to get into an operating room.

I’m scheduled to meet with a surgeon on October 17 to get the ball rolling toward having this repaired. I hope beyond hope we can get this done quickly. I’d like to be able to focus on my work again. It’s hard to write sensibly about deeply technical things when you’re either in serious pain or on narcotic painkillers (or both).

I’m incredibly fortunate to work with so many people that are tolerant of all the delays and throughput issues I’ve gone through lately while trying to sort this out. It’s been several long months that I’ve been trying to get an answer for this problem. Turns out that three months of physical therapy was probably not the best course of action. Still, I apologize (again) for all the delays, and thank everyone (again) for their patience with me!

At least now I know why I’ve been, at times, nearly out of my mind in pain lately, and needing to take pain medications just to get by. Once this surgery is done, things should be so much better.

 Posted by at 6:20 PM