L10n:Documentation: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
= Guidelines for Creating L10n Documentation = | |||
This page is intended to lay out guidelines to help keeping the documentation consistent in content and style, easy to find and up-to-date. | This page is intended to lay out guidelines to help keeping the documentation consistent in content and style, easy to find and up-to-date. | ||
= Information models and doc purposes<br> = | == Information models and doc purposes<br> == | ||
== Wikimo == | === Wikimo === | ||
Documents that are on wiki.mozilla.org | Documents that are on wiki.mozilla.org | ||
| Line 14: | Line 16: | ||
Note that this is the first proposed information model for the WikiMo l10n doc.<br> | Note that this is the first proposed information model for the WikiMo l10n doc.<br> | ||
== MDN == | === MDN === | ||
Documents that are on developer.mozilla.org | Documents that are on developer.mozilla.org | ||
| Line 27: | Line 29: | ||
<br> | <br> | ||
= Style Guide = | == 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 | 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 | ||
| Line 33: | Line 35: | ||
'''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. | '''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<br> == | === Page naming guidelines<br> === | ||
==== WikiMo ==== | ==== WikiMo ==== | ||
| Line 72: | Line 74: | ||
#See the [https://developer.mozilla.org/Project:en/Page_Naming_Guide MDN topic on page naming] for more information. | #See the [https://developer.mozilla.org/Project:en/Page_Naming_Guide MDN topic on page naming] for more information. | ||
== Paragraph & character styles<br> == | === Paragraph & character styles<br> === | ||
==== WikiMo<br> ==== | ==== WikiMo<br> ==== | ||
| Line 82: | Line 84: | ||
For most style information, see the [https://developer.mozilla.org/Project:En/MDC_editor_guide MDC Editing Guide] and the [https://developer.mozilla.org/Project:en/Writer%27s_guide 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.<br> | For most style information, see the [https://developer.mozilla.org/Project:En/MDC_editor_guide MDC Editing Guide] and the [https://developer.mozilla.org/Project:en/Writer%27s_guide 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.<br> | ||
= Misc. = | == Misc. == | ||
== Documents updated on branching == | === Documents updated on branching === | ||
*[[L10n:Branches]] | *[[L10n:Branches]] | ||
== Templates for creating L10n wiki pages == | === Templates for creating L10n wiki pages === | ||
*[https://wiki.mozilla.org/Template:L10n:WikiEntry WikiMo] | *[https://wiki.mozilla.org/Template:L10n:WikiEntry WikiMo] | ||
*MDN | *MDN | ||
== Background information == | === 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 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]]. | ||
Revision as of 22:22, 21 November 2011
Guidelines for Creating L10n Documentation
This page is intended to lay out guidelines to help keeping the documentation consistent in content and style, easy to find and up-to-date.
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
- Always use the L10n: namespace.
- Bad: Firefox_productization_guidelines
- Bad: L10n_Firefox_Productization
- Good: L10n:Firefox/Productization
- For hierarchies, use /, not :. This will create breadcrumbs automatically.
- Bad: L10n:Firefox:Productization
- Good: L10n:Firefox/Productization
- Prefer hierarchies than longer names if you need to disambiguate.
- Bad: L10n:Firefox_Productization
- Good: L10n:Firefox/Productization
- 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.
- Don't repeat yourself:
- Bad: L10n:Firefox/Firefox_Productization
- Good: L10n:Firefox/Productization
- Add localization-related categories.
- Use [[Category:L10n]] anywhere in the contents of the page.
MDN
- Always use the format langcode/Localization/yourpage.
- Bad: /en/Create_a_new_localization
- Good: /en/Localization/Create_a_new_localization
- Bad: /en/Create_a_new_localization
- Prefer hierarchies to longer names to avoid ambiguity.
- Bad: /en/Localization/Tools_Narro
- Good: /en/Localization/Tools/Narro
- Wherever possible, simplify.
- No repetitions.
- See #4 above.
- 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
- 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.
Misc.
Documents updated on branching
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.