- Analyze documentation usage
- Choose a language for the documentation
- Write language choice and the reason in the documentation
As an example:
`This documentation is written in english, because english is the standard for technical documentation about software <http://docness.readthedocs.org/conventions/index.html#english-is-standard-for-software-development>`_.
Keep in mind that the language of the documentation is related to documentation usage: who does read it? Who does write it?
English is standard for software development¶
For technical documentations related to software, english is recommended, because it’s the standard in software industry. Programming languages and code are written in english. So should be their documentation.
Guidelines for non english-speaking developers¶
A common scenario in countries where english is not a natural language:
- a team develops software
- some team members don’t speak english, or at least not well enough to be efficient with english.
So english doesn’t sound natural to this team... Let’s consider other points of interest, so that you can base your choice on pragmatic values.
How much is english a useful skill to develop software?¶
Since most software documentations, articles, tutorials are written in english, learning english is truly useful. For developers, english language is valuable.
So the question is: in the context of the project, can the team learn english? If the answer is “yes”, then english remains a good choice. Some helpers:
- do team members actually are interested in learning english?
- compare estimated learning cost to estimated benefits of english skill.
Notice that, if some developers speak english, they can help others while doing code review or pair programming.
How many foreign-speaking developers contribute to the software?¶
Think about collaboration and maintenance. May external developers contribute to the project? Which languages could be used for communications?
The documentation language should be one in the list of possibilities.
Notice that, as a universal communication language, english has chances to be in the list. The more “international” or “open” is your project, the more english is a good choice.
How much would be a translation?¶
Whatever the language choice, you may have to translate the documentation one day. So, if you are not sure about the suitable language, consider the cost of translation.
If the cost is low, you may try a language now, and wonder about languages later, when necessary. Just make sure you defined “when necessary”.
As an example, if your documentation is about 200 words, you’d better write it now and translate it later, if necessary, rather than learn english then write the docs. But, the question should be asked again if the documentation reaches 5.000 words.
If only you have to¶
Support multiple languages if only you have to.
One use case where you have to support multiple languages is a end-user documentation of an international service:
- you provide a service or product in multiple languages.
- users speak several languages.
- you provide support for this product in multiple languages.
- so the end-user documentation is written in multiple languages.
Then here is an example where multiple languages are not required... You provide a service to developers. Since your service is world-famous, users speak various languages. But your interface is user-friendly and most developers are used to english... so you don’t have to localize the end-user documentation.
If only you can¶
Support multiple languages if only you can.
Keep in mind that supporting several languages means lot of work: translations, coordination of translation teams, maintenance.
As an example, if you often release original documentation, you have to translate often, or translations would be obsolete. And obsolete (i.e. wrong or incomplete) documentation is generally more harmful than untranslated one.
Sometimes, you can’t support multiple languages yourself, but commmunity can. As an example, the PHP documentation is available in several languages. The original documentation is english, then translated in several languages. In that case, the community is big enough to support the translation process. In fact, here, original documentation and its translations are managed as distinct products.
As separated documentations¶
When you have to support multiple languages, you’d better create distinct products (documentations) which are linked, instead of a big product which contains it all.
- separate maintenance: if a documentation is broken, it doesn’t block others.
- separate contributors: original authors create the reference, then translators translate. You shouldn’t block the release of original content because a translation is missing.