Sorry for crossposting, this may be interesting to multiple groups.
---
Native Lang Leads,
I have been talking about the layout of the Documentation section
in the OOo wiki at OOoCon this year and have been discussing this
matter with some of you in person or via email.
I would like to describe the problem again in this mail and
propose solutions. I would also like to ask you to give your
opinion soon so we can move to a multilingual docs approach soon.
We are focussing on implementing a solution on the wiki.
I know that there are other options but they would include the
usage of other tools and processes and those would require
additional setup, maintenance, and learning effort. These
may be an option later after we had a chance to go through
a thorough evaluation phase. But for now I would like to
approach that pragmatically.
PROBLEM STATEMENT
-----------------
The Documentation project created a structured subsection of
the OOo wiki that is intended to carry all documentation
content to allow easy collaboration (there may be exceptions
to the rule but they are out of scope for this discussion).
a) Many native language communities have created a rich set of
documentation that is not available in other languages.
b) The Documentation project contains much content that is
not or only partly available in other languages.
c) Switching between languages in the wiki is not
straightforward
PROPOSED SOLUTION
-----------------
The solution would include having a fixed agreed-upon structure
for documentation that would allow to place different doc
languages side-by-side.
If all languages follow the same, well-defined structure scheme
it would be easy to implement a language switcher in the wiki
that does the switch programmatically without having to
maintain matching tables.
This only applies to documentation. The mother native-lang
project may still keep its wiki structure as preferred.
IMPLEMENTATION
--------------
The structural scheme of the Documentation wiki content is as follows:
wiki/Documentation/$DocTypeOrBook/$SubSections/$SubSubSections
Examples for $DocTypeOrBook are
- FAQ
- HowTos
- OOoAuthorsManuals
- BASIC Guide
Examples for $SubSections are
- FAQ/Writer
- Howtos/Calc
- OOoAuthorsManuals/Getting Started Guide
- BASIC Guide/Language
$SubSubSections are furthr subdivisions (if required). I think you get
the idea.
The idea is to maintain a parallel structure for "native languages"
alongside the docs, for example:
wiki/Documentation/FAQ for FAQs in en, or
wiki/Documentation/en/FAQ for FAQs in en
(would require move of topics in the wiki)
wiki/Documentation/fr/FAQ for FAQs in fr
wiki/Documentation/de/FAQ for FAQs in de
Likewise, for a particular FAQ, for example:
wiki/Documentation/FAQ/Writer/General/HowToFormatACharacter (in en)
wiki/Documentation/fr/FAQ/Writer/General/HowToFormatACharacter (in fr)
wiki/Documentation/de/FAQ/Writer/General/HowToFormatACharacter (in de)
The langugage ISO code after the wiki/documentation part
of the path would be the identifier. This approach would allow
to use Google to either
* search documentation in all languages by searching
through wiki/Documentation
* search documentation in a particular languae by searching
through, e.g. wiki/Documentation/fr
(this would require to move all English documentation to
wiki/Documentation/en)
Switching languages would be handled by a language bar
that is easy to be set up and switches languages by
changing the language ISO coide in the URL.
*However*, this requires the wiki pages to share a common
page name. In the current mediawiki version, this page
name is also displayed as the page title. I understand that
it is inacceptable for a non-English wiki page to display
an English page title.
With the updated wiki engine (that will hopefully be available
soon), however, we will get the DISPLAYTITLE functionality that
allows a different title to be displayed. This would allow the
pages to share a common page name, but still display a
localized title.
We would also need to agree upon a wiki page title scheme
that makes it easy to handle the URLs. Engslih being the
lingua franca of IT, I propose to use English page names
for the wiki pages. That means, even if you create a French
page inside the French Documentation hierarchy it would need to
have an English page name (that would only affect its URL!).
We also need to have a basic migration strategy in place to
handle existing documents without too much hassle, meaning
moving them to the new hierarchy and possibly renaming them.
The result of all this would be that a Documentation page
contains a language bar marking the currently shown language
and all potentially available languages. Since mediawiki
displays links to non-existing pages differently, it's readily
visible which pages need translation and which languages
are available for a given page.
Clicking that language would bring you to the localized
version of that page. This localization does not have to be
a "mere" translation. Instead, the native-lang community
can decide to describe a given topic in a completely different
way depending on the cultural requirements.
Another issue that must be addressed is how to get notified
if wiki page localizations get out of sync. To be able to
do that, one must define a master language and I don't know if
we actually want to do that.
Thanks for your help and thoughts on this
Frank
--
Frank Peters, Documentation Project Co-Lead
The OOo Documentation Project:
SIGN UP - PARTICIPATE - CONTRIBUTE
IT'S FREE! NO OBLIGATIONS!
http://documentation.openoffice.org
http://wiki.services.openoffice.org/wiki/Documentation
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@native-lang.openoffice.org
For additional commands, e-mail: dev-help@native-lang.openoffice.org