Don’t forget localization
I was reading a list of seven tips for improving technical writing, and the first tip gave me pause:
1. Analogy – provide a comparison or analogy to describe how something abstract works.
Not everyone is as familiar with the system as you are. Try to help the reader along by giving as much direction as possible so they see the bigger picture.
Once they understand how the system works at a high level, they will have more confidence in reading the more technical details.
If your content is going to be localized, comparisons and analogies are going to be problematic because they are often culturally specific. Here’s a good example of how an analogy had to be changed in marketing material so that it made sense to audiences in different parts of the world:
When the Walt Disney World Resort created promotional material for a North American audience, it stated that the resort is 47 square miles or “roughly half the size of Rhode Island.”
Outside of North America, many people don’t know about Rhode Island, and this analogy would have no meaning. Walt Disney wisely chose to customize the material for each target market. For instance, in the UK version, the material states that the resort is “the size of greater Manchester,” and in Japan, the resort is described as the size of the subway system.
Disney may have the deep pockets to pay for rewriting marketing content for various audiences, but I suspect there are few technical documentation departments these days that have the money or resources to reformulate analogies for different regions. You’re better off avoiding analogies altogther when writing technical content.