Aug 292012

Even though I’m taking time off from work this week, I still want to share the news that we have a new update to MDN’s Kuma wiki platform for you today! We have some nice improvements for you this time around:

  • If you accidentally leave an editor page (by clicking the back button or going to a new page using a bookmark or the URL bar), a draft of your current state is saved locally on your computer. Returning to the page will offer to restore that draft. The recently-added alert when leaving a page has been removed in favor of this change. This is freaking awesome stuff that I’m totally stoked to have!
  • The link editor now prefills the URL box with “/locale/docs/”, and when you tab to that field, the text entry point begins after that text (instead of selecting the existing content), so you can just start typing the rest of the URL. This should provide a subtle, but helpful, improvement to the amount of time it takes to create new links.
  • In-wiki redirects created using the REDIRECT syntax were previously, incorrectly, 302 temporary redirects. They are now 301 permanent redirects. This will improve SEO as well as being more semantically accurate.
  • A rule in the CSS for edit pages that was attempting to load a non-existent image has been corrected; this was adding up to 0.7 seconds to the load time of the edit page, every time, due to the delay caused while the 404 page was being loaded.
  • The text in the “Revision comment” box that explains what the box is for has been changed slightly. It’s probably not worth mentioning even; that’s how slightly it’s changed!

Our team continues to do fabulous work — and fully half of the development team is on vacation this week, so this just shows how great they are, since great stuff continues to happen anyway.

I’ll be back at work from my vacation week the day after Labor Day (that is, I’ll be back on September 4th). See you then!

 Posted by at 5:28 PM  Tagged with:
Aug 242012

ZOMG! We pushed a second update today. And not as a panic move, but because we have more, tested, features and enhancements to give you! To wit:

  • The user interface for reverting changes has been implemented. The history list now offers a Revert link next to each version of the article. Clicking this creates a new version of the article based on the version you selected.
  • The JavaScript code for the editor is no longer loaded if you’re not logged in; this will improve page load times if you’re not logged into the wiki.
  • The “Save and keep editing” button now clears the revision comment when clicked, so you don’t accidentally re-use a previous edit comment.
  • The label of the revision comment box has been corrected; it accidentally said “Review comment.”
  • The revision comment box has been moved above the tag editing area, since it will typically be used more often.
  • Fixed a broken image reference in the site CSS.

This is another nice set of usability improvements. It’s very exciting to be getting so much good stuff so quickly!

 Posted by at 6:22 PM  Tagged with:
Aug 242012

We’ve just pushed another modest update to the Kuma software that powers the MDN wiki. The biggest changes here are modest improvements that will affect our international community. Here’s a quick list of what’s changed:

  • Persona login support has been enabled for all locales, including those for which there’s no Persona translation at this time. Previously, we had a specific list of locales for which we supported logging in, which kept a lot of people from editing MDN. No more!
  • The text “BrowserID” has finally been corrected to “Persona” everywhere.
  • The <s> and <tfoot> elements are now on the editor’s whitelist.
  • Translation screens for right-to-left locales now put the original English text on the right instead of on the left; this should feel more natural for people in these locales.
  • Demo Studio has been updated to use the changed URLs for documentation post-Kuma launch.

As I said, this is a pretty modest update, but the login and localization improvements should make our localization community ever-so-slightly happier! Enjoy!

 Posted by at 2:23 PM  Tagged with:
Aug 222012

That’s right, everyone! We’ve got another update to the MDN wiki already, just one day after the last update! Before we get into today’s update, I’d like to note that yesterday’s caused a noticeable improvement to page load times. I’m quite pleased!

This update is, again, fairly small, but has some nice improvements that will impact productivity in helpful ways, so it was worth getting pushed to our production servers quickly.

Here’s a quick list of what’s new:

  • The revisions RSS feed has undergone the first round of updating to improve its usefulness; among other things, sequences of changes to the same document are now all included in one entry in the feed, and there’s now a side-by-side diff of the HTML, similar to the one in the in-site revision history. It is not yet pretty; however, its output is more useful and extensive. More work will be done over the next few weeks to make it better. We promise!
  • The site was serving up several HTML <meta> tags that served no useful purpose. These have been removed.
  • The copyright notice at the bottom of the page was not correct; it has been updated to read “© 2005-2012 Mozilla and individual contributors”.
  • A bit of JavaScript that was being loaded twice is now only loaded once.
  • A bug that caused the display of the parent of a page in the editor to be wrong if the parent has moved has been fixed. This is a step along the road to adding support for moving pages, which is coming Real Soon Now™.
  • Attributes for the <select> element are now whitelisted so that examples will work correctly.
  • The correct permission is now checked for letting users attach files to articles. This should help improve the availability of this feature!
  • The ability to delete a revision has been removed and has been replaced with a revert feature; you can now choose a version of an article to revert to. Doing so makes a copy of that version and makes a new version of the page with those contents. This makes undoing changes less destructive, and much safer. However, the UI for the revert feature has not landed yet. It will come very soon.
 Posted by at 5:45 PM  Tagged with:
Aug 212012

We’ve pushed a new code update to the MDN wiki system! This is a fairly small update in terms of the number of changes, but some of them are really great to have!

  • You may now add a revision note when saving changes; these notes appear in the revision history for the page. I’m so happy to have this feature back!
  • Fixed a bug that prevented you from doing two revision comparisons in a row.
  • Fixed some skin bugs to make the content more consistent.
  • Fixed a case in which ARIA @ROLE was used incorrectly.
  • The base JavaScript files used by the site (for Persona and for the “Tabzilla” interface in the page header) are now marked as being allowed to run asynchronously. This will hopefully improve performance, at least slightly.
  • The “Report a Bug” button has been removed; we’ve been overwhelmed with reports and need time to wade through them!
  • The links for Persona have been updated from the now out-of-date addresses we were using.
  • Spaces are no longer accepted in slugs; they were breaking pages (and weren’t meant to be allowed in the first place).
  • The localization update needed RSS feeds now include a link to the diff so you can see what changed in the English version of the page.

In all, a few very useful changes and a lot of minor bugs fixed. Not bad, considering it’s only been a couple of work days since our last update!

It’s interesting how everyone on the Kuma team is so excited about our progress that we enjoy sharing the fixes as quickly as we can! Expect more soon!

 Posted by at 8:01 PM  Tagged with:
Aug 162012

This evening we pushed a new update to MDN’s Kuma wiki platform! That’s right, twice in one week! Let’s take a look at what’s new tonight.

RSS feed improvements

We’ve made a bunch of improvements — and additions — to our RSS feed offerings. You can see our updated RSS feed documentation for details.

  • We now have new RSS feeds that list the documents in your locale whose original language’s content has changed. For example, if en-US/docs/CSS/color changes, the new l10-updates feed for other locales will tell you so. This should be a huge help for localization teams!
  • Feeds are now filtered by locale, so you can see changes in just the locale that interests you.
  • You can still get a feed that lists changes in all locales, using the new ?all_locales option on your URL.
  • The publication date for each entry in the RSS feeds is now the article’s modification date instead of the date at which the latest revision was created.
  • A bug causing all links in feeds to be in the current request’s locale instead of in the locale corresponding to the item has been fixed.
  • The maximum number of items reported by each feed is now 100 instead of 15.

There’s a lot more we’re going to be doing with the RSS feeds, and hopefully you’ll see further improvements in this area next week.

Editor enhancements

In addition, we’ve made some enhancements to the editor and page management functionality.

  • When you try to leave a page that you’ve edited content on (for example, by clicking the Discard button), you now get an alert warning you, instead of just losing your changes.
  • The style drop-down box has been resized to fit its contents better.
  • A bug in the revision history page that caused an error if you forgot to choose two versions before clicking the “Compare Revisions” button has been fixed.
  • Fixed an overflow glitch on localization editor pages.

Content handling improvements

There have been some improvements to the handling of certain types of content as well.

  • The following elements are now allowed; previously, they were being filtered out: bdo, del, ins, kbd, samp, and var.
  • A bug has been fixed in parsing of JSON argument strings in templates.
  • Fixed a KumaScript bug that was causing truncation of unquoted numbers at the decimal point, if one was present.

That’s it!

That’s it for this update. This is a lot of nice stuff, and, again, is our second upgrade in a week. That’s just awesome! Well done, guys!

 Posted by at 9:25 PM  Tagged with:
Aug 152012

Last week, the core MDN team of writers (Mozilla staff writers as well as a few contributors) and our development team met in Toronto to talk about planning for the next few months of work on the MDN wiki, Kuma. Today, I’m going to share some information about what we discussed and what we’re hoping to do to make the system even better.

Launch retrospective

First off, our launch went remarkably smoothly. It took a matter of minutes, and while the development team and at least one IT representative hung around waiting for something to go wrong, nothing ever did. Gradually they wandered off to find less boring things to do.

Now that, my friend, is a successful launch. Boom.

How we think about prioritization

There are basically four key priority areas:

  1. Security concerns.
  2. Stuff that makes reading and using the site better.
  3. Stuff that makes writing content better.
  4. Stuff that makes administrating the site better.

Now that we’ve reached basic functionality, remaining security concerns are of course top priority. After that, on average, group 2 is the most important. If something actually breaks content, that’s a serious issue and one we want to address relatively quickly, by and large. Group 3 is the second most important. A documentation site isn’t much good if you don’t have documentation, so making the creation and editing of content work well is key. The fourth group is typically the least important, unless failing to address an administration issue means one of the others is jeopardized.

What’s next, then?

So let’s talk about what we’re going to do next. Obviously, there’s lots of stuff we want to do. However, we can (and did!) prioritize this list, at least to some extent. This doesn’t result necessarily in a list of exactly what will happen in what order, because it turns out that if you throw all the really important, really hard stuff at your development team all at once, they tend to freak out. Go figure!

Instead, what we’ll be doing is picking a couple of big things off the list, and a few smaller but also pretty important things, and mixing it up a bit over time. The team works on one-week sprints (although they might go to a different sprint length sometime in the future). For example, today they’re starting on a sprint that ends on August 22nd. You can take a look at that link to see what they’re going to be tackling between now and then, as well as the status of each item. There’s some excellent stuff on there, which covers a wide selection of users. A few key items that I’m particularly excited about:

  • For reading and using the site
    • Breadcrumbs on different languages can be wildly different, even if the hierarchy is the same.
    • Pages that have special characters in their slugs are missing (they’re actually there, but hidden in the UI right now).
  • For writing and editing
    • Make logging in work even on languages without a BrowserID localization.
    • Add the edit summary so you can comment when saving changes.
    • Improvements to the revert UI.
    • Improvements to the RSS feed for recent changes.
    • Many, many localization improvements.

Note that we’re not doing anything site admin related in this sprint. That’s because you, the user, are more important. That and we’re also site users! This stuff drives us nuts too.

The next few months

Over the next few months, we’ll be continuing to work on things like:

  • Support for moving pages (and hierarchies of pages).
  • A system for displaying live examples, with support for letting the user experiment with and try out changes to the code.
  • Editing just a section, instead of the entire article; this is mostly finished but has some bugs that need to be resolved.
  • Support for embedding SVG diagrams.
  • An API for allowing software to add content to the wiki using a POST API, with a token system for security.
  • Improvements to administration, especially user management features.

There are other things that are likely to be worked on too, but it’s too early to know which they’re liable to be.

At any rate, this gives you a good idea of where we are and where we’re going. Feel free to drop into the #mdndev channel on IRC, where you can watch our valiant development team at work!

 Posted by at 5:16 PM
Aug 142012

We updated the MDN wiki software today. Let me give you an overview of the changes, most of which are not immediately obvious, but several of which are really important.

Before I do that, however, let me mention this: one big advantage to the new Kuma platform we’ve built is that we can push new versions very quickly and easily. Once changes are in and reviewed, the site can be updated in just a couple of minutes. This is a big win for us; we can identify and fix bugs quickly, and update the production site in a matter of minutes after the testing is finished. Indeed, there may be weeks in which we update the site several times, just because it’s easy to do. The exact pace at which updates occur will of course depend on exactly what’s changed and the risk/benefit ratio.

OK, on to what’s new!

Changes in this update

  • We fixed a security risk by upgrading to a newer version of CKEditor.
  • The style drop-down now offers an option to mark the selected text as being the Search Engine Optimization (SEO)  summary for the article. This text, which is given the class “seoSummary”, is reported to robots crawling the site as the summary of the article. This lets you choose the best possible text as the article’s summary to improve its SEO. By default, the first paragraph is used; however, this is sometimes not useful text. See the screen shot below for an example:


SEO summary example

  • Once you’ve selected a summary block, it looks like this in the editor, so it’s easy to spot:

Screenshot of what the SEO summary looks like in the editor

  • Editing translations no longer causes the table of contents for the page to vanish into oblivion.
  • Modernized the character set metadata in the HTML header block.
 Posted by at 3:35 PM  Tagged with:
Aug 142012

In the past, I’ve blogged about how to do compatibility tables on MDN. After I wrote that post and we started switching to the new tables, someone (I honestly don’t know who) added two new macros: {{CompatTableDesktop()}} and {{CompatTableMobile()}}. These were never really a good idea, since they accepted parameters in a mandated but hard to read order and generated the tables for you. But we’re open to new things, and we let people use them.

It turns out this was a mistake. Not only are they hard to read, but it turns out they’re entirely incompatible with KumaScript.

So these templates can no longer be used. Instead, you need to embed the tables as documented on the compatibility tables page. Any places where these two templates are currently in use is broken and will need to be updated to properly and directly embed the tables.

The core team will fix them as we find them, but if you see one, please update them!

If you have a proposal for a better way to do this, feel free to offer it. Just keep in mind you can’t pass arrays to templates, and you can’t nest templates. These are both things that these two templates were relying on, and are not supported by the Kuma platform.

 Posted by at 12:48 PM
Aug 132012

In the past, creating warnings and notes using templates could sometimes be tricky. That’s because the MindTouch software we used to run didn’t let you start an HTML block in one template, have some text, then use another template to end the block. The Kuma wiki we use now, however, does allow this. This helps alleviate some of the issues we have with the fact that you can’t nest templates in Kuma articles.

To create a complex block, you can now do this:

{{WarningStart()}}Here’s a bunch of text that occurs in a warning, complete with {{bug(2345)}} calls to other templates.{{WarningEnd()}}

Example warning box


{{NoteStart()}}Here’s a bunch of text that occurs in a warning, complete with {{bug(2345)}} calls to other templates.{{NoteEnd()}}

An example note box

We’ll be adding more templates for doing things like this, some of which will really help a lot (such as for building compatibility tables, which are broken right now if you use certain templates for building them). However, that will mean twiddling existing content to use them. Unfortunately, adding support for nested templates is a big project, and we have other things that need doing right now.

If you need a template like this and don’t know how to create it, take a look at those templates’ code. If you still don’t know, ping me and I’ll see what I can do to help. Since KumaScript is really just JavaScript with some provided APIs, you should be able to adapt them pretty easily though. If you need template editing permissions, let me know, and if I know you, you can probably have them.

 Posted by at 3:17 PM