Talk:Documentation Strategy

From Open Source Ecology
Jump to: navigation, search

Please, remember documentation will be translated.

I just looked at and took the essentials (but there are some links):

Translation should be considered early in the documentation process.

Documentation is text (lightly or heavily formatted), annotated images, and video with subtitles and voice. Out of all that, text is what's touched by the translators. It is created and then recreated when the designs evolve. So, from early in the process, access to that text is vital for the translator.

  • Hardest access comes in the shape of heavily formatted PDF files.
  • Wikis have their advantages for cooperation, once you have user/pwd and learn some syntax.
  • Even easier to use is where you just write away with a chat window on the side. Etherpad is pure joy, with others typing away in parallel, you can chunk out the work flexibly as you go along (always finding something easy is a must!), and you can swap help by typing directly in the edit window, or in the conversation window.
  • Images should have no text, and that's relatively easy. But what about diagrams?
  • Subtitles should be separate from the video itself. Remember to speak 10% slower than you'd want to, because some languages have longer words than English.

Are there tools that decouple format from content? I've used and it's good for some things. You need to log in to google, I think. Google's translation toolkit divides sentences up nicely, keeps format and links, and can even suggest an automatic translation. There's the possibility to use or even create glossaries, which is an important tool for technical translations - and technical translations is what we do.

Translators need help, mostly from each other but also from those on the ground. Glossaries etc.