L10n:Documentation

Information models and doc purposes

Wikimo

Documents that are on wiki.mozilla.org

• should be related to project management
• should be specific to Mozilla project

Note that this is the first proposed information model for the WikiMo l10n doc.

MDN

Documents that are on developer.mozilla.org

• should be related to development
• you should be able to abstract them from the Mozilla project

Note that this is the first proposed information model for the MDN l10n doc.

Style Guide

As each wiki tool provides different features for character and paragraph styles, this will attempt to address styles that are compatible between the two and identify uses for those which are unique to each wiki

Note: Please include a brief summary of your changes when editing a page. To do this, enter your changes in the text field found below the editor box.

Page naming guidelines

WikiMo

1. Always use the L10n: namespace.
   • 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 categories.
   • Use [[Category:L10n]] anywhere in the contents of the page.

MDN

1. Always use the format langcode/Localization/yourpage.
   • Bad: /en/Create_a_new_localization
     
   • Good: /en/Localization/Create_a_new_localization
2. Prefer hierarchies to longer names to avoid ambiguity.
3. Wherever possible, simplify.
4. No repetitions.
   • See #4 above.
5. Add any of the following localization-related tags by selecting the "Edit tags" button and enter the tag name in the field provided.
   
   • Localization, Internationalization, Localisation, Localizability, Translation, Language
6. See the MDN topic on page naming for more information.

Paragraph & character styles

WikiMo

For most style information, see the Mozilla WikiMedia Editing Guide. This includes the appropriate uses for toolbar styles, templates, tables, hyperlink formats, anchors, and categories. Before you begin editing or creating pages, please familiarize yourself with these styles and use them where appropriate.

MDN

For most style information, see the MDC Editing Guide and the MDN Writer's Guide. This includes the appropriate uses for toolbar styles, templates, tables, hyperlink formats, anchors, tags, and deleting pages. Before you begin editing or creating pages, please familiarize yourself with these styles and use them where appropriate.

Images and graphics

The following are some guidelines to consider when adding images and graphics to L10n documentation within either the Mozilla wiki or the MDN wiki.

1. Ensure that the image or graphic is relevant to the topic.
2. The image or graphic must fit within the body of the page.
3. A screenshot image must add information to the topic that cannot be adequately described using words, character, or paragraph stylings.
4. A non-screenshot image or graphic should be both aesthetically pleasing and instructional.

Misc.

Reviewing L10n doc

Here is a brief outline of what to look for when reviewing and providing feedback for L10n doc on both the MDN and Wikimo. Note that doc awaiting reviews remain in the draft state until they have received feedback and have been cleared for publishing. Publishing means that categories are added to the page for proper indexing.

Below you'll also find a checklist of questions to ask yourself while performing the review. Please base your feedback on these criteria.

Types of doc for reviewing:

1. Brand new doc
2. Revisions to an existing doc
3. Re-draft of an existing doc

Doc elements to review:

• Target audience
• Page structure
• Use of styles (i.e., bold, italics, etc.)
• Working and relevant links
• Overall flow of information

Review checklist

1. What type of doc am I reviewing?
2. Who is the target audience?
3. What need is this doc trying to fill?
4. Does what I read successfully address and satisfy the target audience's needs?
5. Does the doc's structure help to make the doc easy to read?
6. Does the language in the doc make it easy to read and understand?
7. Does the doc contain any navigational links to promote a specific information flow? If so, where do they lead?
8. Do the styles (bold, italics, etc.) guide you to key pieces of information in the doc? If not, how could they be better used?
9. Are all of the links functional? If not, please identify those that are not functional.
10. Is the information contained within the doc accurate and up-to-date?
11. Are there any specific details that are missing from the doc? If so, please identify those details.
12. Please rate what you have read on a scale of 1-5 (1=best doc I've ever read; 5=big pile of uselessness) and explain the reason for your rating.

Documents updated on branching

• L10n:Branches

Templates for creating L10n wiki pages

• WikiMo
• MDN

Background information

In the second half of 2009, we conducted an overhaul of the localization-related documentation in Mozilla. You can find more information about it on the project's page at L10n:Better Documentation.

In the second half of 2011 we, once again, endeavored to overhaul all localization-releated documentation. This page has been a result of that overhaul and outlines the high-level changes implemented within the doc.