Analysis of current CL10n docs
[Here's a tentative outlook upon our documentation. Comments and writing help are warmly welcome!]
What we have right now
- AppleGlot and related localization tools
-
- Provides instructions about downloading the tools (both AppleGlot&Co., and XCode)
- Provides info about using Interface Builder
- Provides a link to download the latest palettes needed (hosted on-site)
- No info about XCode requirements - No info about Mac OS versions required/supported
- iLocalize introduction
-
- Provides a link to iLocalize download page and basic info about getting a free license
- Info about setting up a new l10n project importing an existing l10n
- No info about starting a project from scratch
- Info about preferences set up
- Info about setting up a glossary
- Info about about updating project with a new base package (that is: when the original/English Camino is updated)
- Info about exporting a completed l10n
- No info about setting up paths for nibtool and Interface Builder
- Localization QA: checklist
-
- Very basic check-list for reviewers
- List items are grouped by "where to look"
- Information about team building and tasks should probably be replicated also in the introductory part of the docs
- Talkback items are becoming obsolete
- We need another page for localizers, to spot several exceptions or special treatments required by some interface elements (see Bug 485146 comment #13)
- We could maybe leverage iLocalize as a review tool
- Packaging guidelines
-
- We could probably axe this page, given that it's become convenient to post full application bundles and that sometimes PackageMaker becomes a moving target across OS releases
- Reporting Camino localization bugs
-
- Verify that the instructions are up to date with current bugzilla interface
- No info about the bugzilla account being a field in the user profile at Cl10n
What we want to have
- Getting started
-
- Info about getting the right tools and put them into the right places
- Info about leveraging the cl10n community (site + mailing list) for better and more efficient translations
- Info about System/Software requirements for the supported versions of Camino
- Info about what versions of Camino are supported
- iLocalize primer
-
- Info about setting up a project: from scratch or from previous localized builds
- Info about preferences and paths definition
- Info about importing a new base (updated original Camino)
- Info about exporting and distributing a l10n
- Translator cheat sheet
-
- List of peculiar items that need special treatment in iLocalize/Interface Builder (see example Bug 485146 comment #13)
- Localization QA: checklist
-
- Expand the current checklist
- Eliminate Trackback references
- Suggest that also reviewers might use iLocalize, especially to check strings; elaborate on the possibilities offered by iLocalize (items marked for review)
- Reporting Camino localization bugs
-
- Add info about why filling the bugzilla account profile field is important
- Check validity of bugzilla instructions
- Update screenshot
Comments
Non-app content
The new documentation also needs some information about content that's not inside the application that needs translated, i.e., the Read Me, Release Notes, and the update description file(s).
The update description file in particular requires that I remember to prompt new translations about it, so a note about how to look for the appropriate bug (we could link to a query that includes fixed bugs over the last year with the word "update" and the "Product Site" component) would be useful.
The docs could also describe how the release notes and readme are typically modified, e.g. the readme changes very little, the alpha/beta release notes look nothing like the final notes or the point-update notes, and so on.
Time required?
One other thing I wondered about: would it be useful to list the approximate number of hours of work required when
Or would that tend to scare people away ("this is too much work") instead? Since we have new translations and translations in various stages of updating from 1.6.x to 2.0, this would be a good time to gather those statistics if they'd be useful.
Localization QA checklist
The checklist that I use for major releases and for any time we add a new language in a point release can be found on the Camino Wiki: http://wiki.caminobrowser.org/QA:Release_Testing:l10n
Not all of the items overlap with what the translator and reviewer should check, but most of them do, so it would be good to incorporate the relevant items into the new cl10n checklist.