Español - Français - Norsk Bokmål

Outdated page

This page is out of date and needs to be integrated with the Documentation Team Guidelines, and probably with documentation for translators.

Writing Documentation


Based on experience on translation and documentation here are some suggestions for those who want to translate and write new documentation on the wiki for their language, and also integrate it "upstream" into the main community wiki of gNewSense.

This attempt is to improve the new localisation rules suggested by the French and Spanish community.

The wiki can be easy and quickly edited, and using these recommendations will increase the potential the wiki has to offer.

Wiki Localization

As the gNewSense community grows there are more gNewSense localizations of the website, mailing list, irc, forum and of course wiki documentation.

Some of the important rules while localizing the wiki documentation, is following the proper url creation based on the WWW localization.

The English page:

will become: for German language pages for Spanish language pages for French language pages for Italian language pages

By doing this, it will be easier for a person who browses through the site to find the translation of a page in her/his own language. It will certainly ease the translation process itself, for the translators will find the original page very quickly.

Another benefit of this naming system will be keeping a standard page layout in the wiki. We should note there is no enforced layout, the pages under a language group are completely under the control of the translation team.

For example

Writing and Integrating Wiki documentation

Writing wiki documentation

As the new communities keep growing the need to write their own documentation in order to solve, help and interact with the community increases. This aids the communities needs, and integrating new documentation "upstream" into the main community requires you follow the same rules as for translation. So please keep in mind these tips while writing new documentation.

If you want to write documentation in your own language, choose the best section to lay the wiki, some of the most used sections are:

Also if you're writing in your own language don't forget to use your localized language characters:

es --> Main:es<<BR>>fr --> Main:fr<<BR>>it --> Main:it<<BR>>de --> Main:de<<BR>>cn --> Main:cn<<BR>>tr --> Main:tr<<BR>>(etc) More on this page:

The title of the page should be in English, so all the community around the world can understand the subject, and contribute it on it if interested.

Just as example:
PageDAccueil --> HomePage
PaginaDeInicio --> HomePage
StartSeite --> HomePage

On this point we can use the (:title :) feature that the wiki allow us to control the title of the wiki to be the one we need to fit our pages language structure. This way we can have the correct title without comprimising the i18n. --> (:title Portada:) --> (:title Page d'accueil du wiki:)

The final product is well structured documentation wiki:

Integrating wiki documentation upstream

If you have already written a wiki page with information in your own language that you want to be available "upstream" (to the main community), you may introduce it to the main community, as example:

This page was first written in Spanish and now is in English, and it must follow all the previous recommendations.

Main wiki -- No i18n ending characters, es, fr, de, cn...
Section -- Documentation
Subject in English -- WritingDocumentation
Wiki i18n source (optional) -- Write a little annotation where the wiki come from, for informational purposes only.

Future of the localised wiki

When the localised wiki is both upstream and downstream, each community will be responsible for the improvement, actualisation and future of the wiki.

This translation, integration and creation structure is on its first reviews, so please stay tuned. If you feel willing to translate, manage wikis, or help to improve this documentation, please report on the general mailing list.


Documentation/WritingDocumentation (last edited 2013-08-30 03:06:23 by FelipeLopez)