Staś Małolepszy

Let’s make the l10n documentation better

This post was migrated from my old blog. Some links might not work.

Abstract: Help us improve the l10n documentation by participating in creating a complete inventory of our documentation resources at Delicious. All you need to do is to bookmark any page with useful l10n documentation content at Delicious and tag it with “for:mozdocs”. That’s all it takes!

This quarter, the l10n drivers team has set out on a mission to improve the current localization documentation experience. The ensemble of the l10n documentation consists of a rather formidable number of resources (wiki documents, articles, blog posts, graphics, etc.). With time, some of them have unfortunately become out-of-date, and one of our objectives is to update our documentation to reflect the changes that took place to our processes, practices, policies, guidelines, tools and infrastructure (like, remove references to CVS in documents about starting new localizations).

But that’s not our only objective. A big goal that I see here is to identify who’s using the l10n documentation (localizers, l10n-drivers, qa, bizdev, build, developers, webdev, marketing… and so on and so forth), and with these targets in mind, reorganize the documentation in a way that would best serve these groups in completing the task they come to the l10n documentation with.

A rough plan (still work in progress) is outlined on the wiki. The first step is to create an inventory of all documentation resources regarding l10n, across wikis, blogs and other documents. What we need is a flexible tool to create a collection of documents and describe them with tags. After some research I came to the conclusion that the best tool for this purpose is Delicious.com. It offers powerful tagging features (like bulk editing tags or creating tag bundles) and allows to export the collected bookmarks to a well-structured HTML file, which will, for example, make it easy (with some basic parsing) to create a graph of all resources that we know of (if we decide we need one). Delicious has also managed to create a thriving community of tools developers who take advantage of Delicious API to create stunning visualizations of relationships between bookmarks or tags (or both). I’m really looking forward to exploring some of the possibilities this will give us and see how we can use them in order to understand and improve our documentation.

And so I have created a Delicious account called “mozdocs“. I would like to use delicious’ tagging capabilities to create a list of documentation articles with tags describing the contents as well as the metadata, like the location of the article (I used the “at” syntax for this, i.e. @wikimo, @mdc, @blog, etc.). Just go to mozdocs’ bookmarks page on Delicious to see those tags in action. I’ll bookmark this very blog post, too, once it’s published, and tag it with “@blog, @stas, documentation.”

Delicous being a social network, it also offers a couple of neat networking features. You can add any account to your network and then post bookmarks for such defined contacts. In other words, you can add “mozdocs” to your network and then use the “for:mozdocs” tag to make the bookmark show up in mozdocs’s inbox!

If you feel like participating in this grand l10n documentation overhaul, I would like to ask you to bookmark any pages that in your opinion contain useful l10n documentation content and tag them with “for:mozdocs”. It doesn’t matter if you think that the page is so obvious that someone else must have already added it. Delicious is smart about detecting duplicates, and even if it wasn’t, I’d rather deal with duplicates than miss an important piece of documentation.

You don’t have to add any tags, but it will certainly help us if you do (and don’t hesitate to add a lot of them!) Also, if you see that an article is out-of-date, please use the “fixme” tag. I’ll be watching this tag and I’ll make sure the articles tagged with it are updated.

Thanks in advance for your help. I’m looking forward to discovering new l10n documentation pages that I haven’t seen yet :) I’m positive that using Delicious will help us tremendously to categorize the articles and identify those that need to be updated or rewritten.

Published on 14.07.2009
Permalink: http://informationisart.com/051

Staś Małolepszy

Thoughts about the Internet, the information society, Mozilla and human-computer interactions.

Latest notes