Bit Stampede

If you hadn’t noticed, the pace of development at Mozilla has really picked up lately. Between the ongoing rapid progress on the Boot to Gecko project, the six-week development cycle of Firefox, the web apps, marketplace, and Persona projects, not to mention other projects, it’s become clear that we need to start being more careful about our documentation workflow.

For that reason, we’re going to make some changes to our documentation process.

What’s changing?

In the past, too many person-hours of writing work have been used documenting technologies that were so far from fully-baked that we’ve had to redo (sometimes more than once) these documents. Often, the docs never get properly updated (I’m looking at you, IndexedDB). This is a huge waste of time in an era in which our excellent developers are pumping out so much new code and so many new APIs at a faster pace than ever.

Instead, we will only document new APIs when we can be given a reasonable degree of assurance that they’re stable.

• For an API that is expected to be standardized, it has, at a minimum, been submitted to the appropriate standards body and gotten through at least one round of feedback and revisions. This will work out enough of the kinks that we can feel good about documenting it.
• For an API that’s expected to be Mozilla-specific, it has settled down and the developers behind it are able to convince the docs team that it’s stabilized.

This likely means there will be times when the documentation team doesn’t feel that something is ready for documentation as soon as other groups would like to see the docs written. This is an unfortunate side effect of the remarkable productivity level of our development team! Someday, I hope our documentation team will be large enough to keep up with them. But until then, we’ll have to be more selective.

How you can help

If you’re a developer, the first, easiest thing you can do to help is to ensure that your code and headers are well commented, and that you use the dev-doc-needed keyword to mark any bugs that will require documentation updates.

A better, and in the end possibly even more helpful, thing you can do is to provide information! Send email (or, better, add notes to bugs) explaining what’s changed and what needs to be documented. Much of the time, dev-doc-needed means that we have to chase down the right people and ask a lot of questions that could have been avoided with the addition of notes to a bug.

You can go even further and actually update the docs yourself. This may not necessarily always be a viable course of action, but if you’re an expert on a topic, it may make more sense for you to spend a few minutes or an hour or two writing about it than to have the writing team have to do all the research of something you already know. It’s a better use of everyone’s time for you to write down a quick bit of information that we can clean up and turn into beautiful docs than for you and us to go around and around for ages until something’s finally written!

If you write a blog post about something that you think should be in the documentation, please either put it in the docs or at least let the docs team know about it!

The writing team hangs out in the #devmo channel on IRC. Feel free to drop in and ping us with your input or suggestions.

At this point, it’s all about making the best possible use of everyone’s time while turning out not just great code, but great documentation. Because what good is your awesome code if nobody can figure out what they can do with it, right?

At just after 10 AM today, we switched over from our MindTouch based wiki to our new, Mozilla-built Kuma wiki platform for the Mozilla Developer Network, as I announced yesterday that we’d be doing. So far, all’s well!

Over the next week or two, I will be sharing a few suggestions, tips, and bits of advice about the new platform. This is the first of those posts. Today, I’ll be talking about the new template system.

A little bit of history

When we switched to MindTouch a few years ago, one of the key appeals was their incredibly powerful template system. This system made it possible to write complex scripts to automatically generate content. It could be used for everything from simply styling text to looking up information and generating complicated chunks of material. And over the years we used MindTouch, we grew to rely heavily on it.

A key requirement we had from the beginning was that Kuma support similar capabilities, and as a result, Les Orchard and the rest of our development team built KumaScript, an engine for building exactly this sort of scripting. KumaScript is, in essence, server-side JavaScript implemented using Node.js, with provided additional routines to make it possible to access wiki data and inject material into page content at load time. It has powerful caching in place that make it work incredibly fast, and has proven to be an incredibly useful tool for us.

Introduction to KumaScript

If you’ve done any scripting on MDN in the past, you’ll have to adapt a little bit. Les wrote an excellent guide introducing KumaScript, and I can’t recommend it enough. If you plan to do any scripting, or are curious about the system’s capabilities, read that over.

The truly brilliant thing about KumaScript is that it’s fast and is all JavaScript syntax, so it’s incredibly easy to pick up. If you’ve done any web development, you can script on MDN. The only “trick” is that because it’s so powerful, we do require that you get special privileges to edit or create templates on MDN. You can contact me to get those permissions.

If you’d like to take a look at existing templates to see how they work, there’s a page that lists every template. Look them over and get a feel for things!

About templates that are unconverted

Most of the most-often-used templates have already been converted from MindTouch DekiScript into KumaScript templates. There are some that have not been. Because of this, you may occasionally run into pages that don’t look quite right, or even display a box at the top of the page with an error message. Feel free to ping someone in #devmo about this, or fix it yourself if you have the privileges and the time.

If you’d like to see a list of the templates that are known not to have been updated, there is one! If you update one, please toggle off the “Template review” checkbox at the bottom of the page and add the tag “ks-fixed” to it.

We have spent much of the last few months converting templates, and you shouldn’t run into pages with broken ones very often, but it absolutely can happen.

Key differences you should know about

If you use or write templates, there are a few differences you should know about, other than the obvious syntax differences due to being JavaScript instead of Lua-based.

• There’s no longer a weird syntax you have to use for templates with a dash (“-“) in their names. You can use them just like any other template: {{foo-bar(“some parameter”)}}.
• You can’t run KumaScript outside a template like you could with DekiScript. All KumaScript code must be in a template; MindTouch would let you run arbitrary script on any page. For security reasons, we no longer allow this. This does have the side effect of making it no longer possible to nest template calls; you can’t do {{foo(bar())}} like you could in MindTouch.
• You can use JSON as the only parameter to a template. This gives you a way to create templates that accept, in essence, named parameters.
• Although we’ve implemented clones of a number of MindTouch APIs as a short-term solution so that we could get online, they should typically not be used by new templates. In addition, only APIs we actually needed have been implemented. From here on out, we will add new Kuma-specific APIs.
• Templates are heavily cached. The output from a template is saved for every set of inputs it receives. If you change a template, it doesn’t get re-interpreted for a given set of inputs unless someone forces it to be by shift-reloading a page that uses it with those inputs; however, doing this does affect all users, not just you. This vastly improves performance but does mean you have the chance of template changes not being seen by everyone right away.
• Some locales’ identifier codes have changed.
• URL paths have changed: instead of /en/JavaScript, for example, it’s now “/en-US/docs/JavaScript”. Server rewrite rules are in place to automatically redirect existing links, but new templates should do it the new way.
• You can’t apply a “nowiki” or “plain” class to text to keep it from being interpreted as a template anymore. Instead, add a backslash in front of the first “{” in the template invocation. This is useful when editing docs about templates, for instance.

Give it a try!

That’s a quick overview of what KumaScript is and what’s different about it. There’s certainly a lot more to discover, so be sure to read the Introduction to KumaScript and feel free to ask for help on IRC if you need it!