We just had an interesting meeting here discussing plans of how to provide translations of our documentations in different languages. I am a big fan of documentation and have given several presentations talking about the why and how of good docs. In essence the “good code explains itself” talk is a big fat arrogant lie. You should never expect the people using your code to be on the same level as you – that would defeat the purpose of writing code.
Fact is that far too much software has no proper documentation at all let alone translations into different languages. This is because there a few issues with translating documentation:
- Price – translation is expensive, which is why companies started crowdsourcing it.
- Quality – crowdsourcing means you need to trust your community – a lot (looking at Facebook’s translation app shows a lot of translation agency spam in the comments – not a good start)
- Updating issues – in essence, you are trying to translate a moving target. With books, courses and large enterprise level software the documentation is fixed for a certain amount of time. With smaller pieces of software and APIs the docs change very frequently and you need to find a way to alert the translators about the changes. If you crowdsourced your translation this is a request on top of another request!
- Keeping sync – different translations take a different amount of time. Translating English to German is pretty straight forward whereas English to Hindi or Mandarin is a tad trickier. This means that translations could be half finished when the main docs change – which is terribly frustrating to those who spent the time translating now outdated material.
- Relevancy – your documentation normally spans your complete offer – however in different markets some parts of your product may not be available or make any sense. Translating these parts would be pointless, but it also means that tracking the overall progress of translation becomes quite daunting.
All of these are things to consider and not that easy to get around. Frankly, it is very easy to waste a lot of time, effort and money on translation. It makes me wonder if there really is a need for translation or if it doesn’t make much more sense to invest in a localisation framework. What you’d actually need to make your English product available for people in other locations is:
- Local experts – this could be someone working for you or a group of volunteers that see the value of your product for their markets.
- Easy access collaboration tools – this could be a wiki, a mailing list or a forum. Anything that makes it easy for people to contribute in their language and with their view of the world. If these tools make collaboration easy without having to jump through hoops people will help you make your product more understandable in their region.
- A local point of reference – this could be a blog or small presence of your company in the local language or a collaboration with an already established local partner or group.
- Moles – most international developer communities have their favourite hangouts already. Instead of building one that might not be used (not every country is going “wahey” when a US company offers them a new channel) it makes sense to have people who speak that language and that you trust be on these channels, listen to what people need and offer the right advice pointing to your documentation.
What do you think? do you have examples of where this is done well and what worked and didn’t work? Here are two I found: