• The L10n Documentation Overhaul

    October 14th, 2009 by seth bindernagel with no comments »

    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)
    2. For hierarchies, use /, not :. This will create breadcrumbs automatically.
    3. Prefer hierarchies than longer names if you need to disambiguate.
    4. If not ambiguous, simplify.
    5. Don’t repeat yourself:
    6. Add localization-related tags (on MDC) or categories (on wikimo)

    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.

  • Nice finds

    April 21st, 2009 by seth bindernagel with 3 comments »

    aboutNow and again, we’ll come across volunteers who speak languages where we do not have a localization, but who look promising to join us for future Firefox releases.  We receive references from everywhere: Gerv forwards me names from the comments on his blog; Gen does outreach at conferences he attends and then sends us information; or we find newcomers through our l10n newsgroup. 

    Soon after, one of us then makes contact to see if the people are ready or willing to start our localization process.  If the answer is yes, we give them the basic set of documents to get a localization going and we then start the work together, oftentimes with Mozilla’s l10n community helping to answer questions along the way.

    Swahili, Romansh, and Oriya are a few in our near-term pipeline.  Which languages are in our longer-term list?  Maybe you saw Gen’s post about a Gecko-based browser in Khmer.  And, here’s a new one: a screen shot from new volunteers who are working on localizing Firefox into Azerbaijani. If you know of some other possibilities, please feel free to share them here.

  • Could a usability change to AMO increase the percentage of compatible add-ons?

    March 16th, 2009 by seth bindernagel with 1 comment »

    I finally got around to updating my add-on that I created last year so it can be used in Firefox 3.5.  After finishing the process, I was left asking myself, could a usability change to AMO increase the percentage of compatible add-ons ready for the next release of Firefox?

    After going through the process, I’ll say that the https://addons.mozilla.org (AMO) team has done a bang-up job with the developer tools.  Take a look if you haven’t already.  I took most interest in the stats about downloads and daily usage of my add-on.  Those figures have driven me to make my add-on better.

    So, here is an opinion on the update experience.  Without trying to be annoying, I found the compatibility update might have taken a few too many clicks into the developer tools page.  Hoping to update quickly, I entered the developer tools section and then went to “Use New Tools” page pictured right below.

    New AMO Developer Tools Dashboard

    I actually clicked on each of the options that you see above to see how to update.  Keep in mind that this is before I read the AMO documentation…someone happened to tell me I could do it through developer tools and I just went there to do it.  Eventually, I was able to update the add-on by clicking on its version number (in my case it was 1.0.).  From there, I changed the drop down option to 3.1b4pre.  You can see that “Compatible Applications” interface below:

    AMO Compatible Applications

    Now, It’s very likely that I am the problem here and not the usability of the site.  Let’s not rule that out.

    But, I got to thinking.  It seems that updating compatibility of add-ons is an ongoing challenge that the AMO team faces during each release cycle.  This MDC link shows how things have changed and users can log into AMO to update.  And, here is a post that describes how addon compatibility will occur for the renaming of Firefox 3.1 to Firefox 3.5.  More and more blog posts will come along about getting ready for Firefox 3.5.  It’s an important goal for AMO.

    But, because I had to click around so much, I started to wonder if we should feature the ability to update compatibility more prominently on the developer dashboard.  Sometimes unsolicited advice can be a bit obnoxious, but I sketched a potential change to that developer tools front page.  (I also filed this bug for AMO developers to consider.)  The drawing is oh-so-simple, but take a look:

    AMO mockup

    My theory is that if we featured this prominently up front, then a subset of add-on developers would update more quickly in advance of each new release.  I don’t know how many have zero code changes from release to release, but it’s probably a sizable number.  The ability to quickly update compatibility would allow add-on creators to get their users beta testing that much faster.   And, perhaps our percentage of compatible add-ons at the time of release of Firefox would go up.

    I realize this update took me a while.  But, I procrastinated updating the <em:maxVersion [Firefox_Version_number]</em:maxVersion> found in the install.rdf file.  Naively, I thought I would have to repeatedly upload an update of my add-on to AMO every time the version number changed for Firefox 3.1 (i.e. ff3.1b1pre, ff3.1b2pre, etc.).  I guess I was reading outdated documentation from Firefox 3.0 days and I didn’t know that I could update the add-on straight from the developer tools inside AMO.  Mea culpa.

    I thought about all this over the weekend because it’s been bugging me that my add-on is out-of-date and incomplete.  Then, I learned how to update.  Sometime soon, I hope to make it more complete for the release of Firefox 3.5 by preparing it for localization, creating icons that look good on a Linux and Windows, and providing appropriately sized icons for those who use small icons in their browser UI.

    For reference, here is the a post I wrote a year ago about writing my addon.

  • Helpful Mozilla localization documentation

    March 5th, 2009 by seth bindernagel with 7 comments »

    Yesterday, I posted in the moz.dev.l10n newsgroup (our main mailing list for communication among localizers) a summary of information for localizers who want to learn about our process, start a new localization, or keep track of all that needs to be done to become an official localization.

    I’ve blogged about this in the past, but am posting a reminder because it’s valuable information.  Also, I heard from a few localizers when I was traveling that the process is still unclear and we need a good checklist of information for people to review as they become involved.

    Here is a checklist (probably more detailed than a simplified checklist because our process has multiple parts) we have so far:

    As you start and continue through the process, these four links will be particularly helpful.  If you are familiar with our process and would like to link to more documentation, please list it here.