Jargon
Technical writing must always be clear, concise, and accessible for those not familiar with technical shorthand.
Jargon​
Jargon can alienate readers and make them feel like they're not smart enough to understand the material. It can also confuse non-native English speakers and create cultural misunderstandings.
To avoid using language that can be construed as jargon, use topic-specific terms and acronyms only after defining them and in relevant contexts. For example, use programming-specific language only in content about programming.
The following table shows some common examples of jargon to avoid:
| Jargon | Suggested alternative |
|---|---|
| corner case/edge case | Rare, unusual, unlikely. |
| use case | Scenario, reason, common use for, example. |
| bootstrap | Explain the actual process that the user should go through. |
Figurative language and idioms​
Figurative language compares one concept to another, usually to help relate an abstract concept to a concrete one. However, figurative language can introduce ambiguity and make text difficult to localize. For example, in certain contexts in the US, reaching a deadline might be described as “running towards the end zone” or “sliding into home plate,” but these analogies are likely to be confusing to non-native English speakers, and they aren’t useful to people who don’t follow American football or baseball.
Idioms are familiar figures of speech that do not translate well to other languages. For example, “cutting corners,” “hit the nail on the head,” and “getting out of hand” make sense to English speakers, but make no sense when translated.
Therefore, avoid brief metaphors and analogies that require the reader to possess some additional knowledge or understanding. For example, instead of saying something is "expensive for the GPU," say it is "resource-intensive for the GPU."
In instructional writing, figurative language can be useful to introduce a new concept or deepen the learner’s understanding. In these cases, make sure that a non-native English speaker, reading the text literally, will understand the figurative language and will certainly be aware it is figurative. In such a case, it is better to use similes instead of metaphors.
| Figurative language | Suggested alternative |
|---|---|
| A render pipeline is the machine that manufactures a 2D image from 3D data. There are several different machines that can manufacture these images in different ways. | A render pipeline defines the process of rendering 3D data as a 2D image. You can think of a render pipeline like a machine that takes in 3D data and outputs a 2D image. Just as there might be multiple machines in a factory that perform a task in different ways, there is also more than one render pipeline you can use to perform the rendering task in your Unity projects. |
Get multiple reviewers to make sure that your copy can only be interpreted as you intend.