Post History

Source: https://writers.stackexchange.com/a/35031
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

This is a supplement to [this answer](https://writing.stackexchange.com/a/35019/1993).

Readers, especially technical readers, notice small variations and especially inconsistencies. If you talk about "removing" a resource in one place and "deleting" it in another, some _but not all_ readers will think that's two different operations. This problem is amplified if your documentation is translated into other languages, because now both the translator _and_ the reader have to interpret your subtle variations.

You can minimize this confusion by consistently using the nouns and verbs already in use in your documentation set. (When something _is_ different from a similar-seeming one, call it out explicitly.)

This does not mean that there is never room for humor or even whimsy in technical documentation. _If it is not unusual in your domain_, you can sometimes be more creative with your examples. Never do this at the cost of clarity, but, for example, you can do this if you need to show some sort of user workspace and the actual content doesn't matter. If you're showing how to lay out a circuit board and your audience is expected to be geeky, it's not wrong to name the project in the screenshot NCC-1701-replicator instead of circuit-2. But don't do it if there are 500 examples in the documentation and you're just changing this one; be consistent in your style throughout the documentation set. I've found that "whimsical" examples are best reserved for shorter, less-formal, stand-alone documents like blog posts and use-case descriptions.

Original score: 5