The L10n Documentation Overhaul

What could be worse than outdated and disorganized documentation for an open source project looking to grow its volunteers and support its contributors?  I’m not sure, but the l10n-drivers had to wake up each day asking ourselves that question about the state of our localization documents.

Something had to change, but to rectify that problem was a daunting task.  Not only were documents outdated or obsolete, but also they were scattered through the Mozilla Wiki (wikimo) and the Mozilla Developer Center (MDC) like wet leaves across a yard, over into flowerbeds and onto the driveway.

Staś (and the l10n team, but primarily Staś) took up the goal of overhauling Mozilla’s l10n documentation.  One result of a lot of work and many meetings was a Delicious page that we created and titled “Mozdocs“.  If you’ve clicked through on that link, you’ll see our attempt to bookmark and tag *every document written* about Mozilla localization.  This became our base for updating all of our documentation.

The Mozdocs Site

Staś determined that the best way to work was to create an inventory of what we had, categorize that, and then begin work.  And so, we began by finding pages in our documentation and adding them to the Mozdocs page.  We then tagged each page we found with something that described it.

Tagging pages became critical in our ability to work on these docs.  Staś created a set of meta tags that tell us some information about the state of the page.  Namely, does it need to be updated, is it obsolete, does it need to be fixed, should it be deleted, and more.  We also have “location” tags that tell us where we found the document (i.e. my blog, Axel’s blog, Mozilla Wiki, etc.).  Lastly, we have general purpose tags that describe the document.

If you’re interested, Mozdocs could be a very helpful page for you to get a sense of what is in the Mozilla L10n inventory of docs.

New documents, New Naming Guidelines

As foreman of the cleanup crew, Staś also determined that we needed to separate our documents properly.  MDC would serve as the place for docs that describe how to develop and localize and can be abstrated from the Mozilla process.  The Mozilla Wiki would serve as the spot for anything specific to the Mozilla Project’s localization process.

Get that?  MDC = how to/abstract from Mozilla; Wikimo = Mozilla process.

As we created and edited documents, we made sure that they were placed on the proper platform.  Furthermore, we started to rename documents using new “Naming Guidelines“.  If you plan to create a new localization document on the Mozilla Wiki or MDC, we are asking that you use the following (Below is one massive hyperlink to the Naming Guidelines from the previous sentence):

1. Always use the L10n: namespace (wikimo only)
   • Bad: Firefox_productization_guidelines
   • Bad: L10n_Firefox_Productization
   • Good: L10n:Firefox/Productization
2. For hierarchies, use /, not :. This will create breadcrumbs automatically.
   • Bad: L10n:Firefox:Productization
   • Good: L10n:Firefox/Productization
3. Prefer hierarchies than longer names if you need to disambiguate.
   • Bad: L10n:Firefox_Productization
   • Good: L10n:Firefox/Productization
4. If not ambiguous, simplify.
   • Bad: L10n:Product/Firefox/Namoroka
   • Good: L10n:Namoroka
   • Good: L10n:Firefox/Productization and L10n:Mobile/Productization are OK, because L10n:Productization is a more general document.
5. Don’t repeat yourself:
   • Bad: L10n:Firefox/Firefox_Productization
   • Good: L10n:Firefox/Productization
6. Add localization-related tags (on MDC) or categories (on wikimo)
   • On wikimo, use [[Category:L10n]] anywhere in the contents of the page.

Our hope is that all new pages that deal with Localization will follow these naming guidelines.

And now, your turn…

As I mentioned, if you’re interested in scanning the inventory of documents, take a look at Mozdocs and the tags we have created.  This could be a very helpful page for you to get a sense of what is in the Mozilla L10n inventory of docs.

Also, if you are finding new documents, can you please tell us and we’ll tag them on the Delicious site?  Staś is the module owner of this site and we are accepting any “patches” to it.  So, if you want to add something, just let us know and we will make the change.