: Re: Bridging the gap between colloquial usage and technical meaning of terms Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general

This issue falls under the "know your audience" rule of (technical) communication. If you are clear on the distinction between canonical definitions and colloquial usage in your product, and if you know something about your readers' points of view, you are able to clarify wherever the distinction is useful or necessary.

A glossary is a great tool/resource. I'm hesitant to recommend only a glossary because when people see a term they (think they) know, they're not going to check the glossary unless -- maybe -- they really get confused. They don't know what they don't know.

In the main content, something like a parenthetical or sidebar tip with a link to the glossary might be useful in a particular context. For example: "Note: REST commonly refers to foo. In this documentation, REST includes any bar. See the glossary for a full explanation."

Load Full (0)

: How to create tension during a conversation In my novel my protagonist speaks to a man while being held at gun point. She (protagonist) tried to kill him. He was her boss, was involved in

@Mendez196

Load Full 5 Comments

: What does "juvenile tone" mean? I often hear the word thrown around, but I don't have any idea of what it is, or how can it be avoided. So, what does "juvenile tone" mean and how can I

@Mendez196

Load Full 4 Comments

: How can a "rip-off" still be good? This time, I'm not really talking about the legal side (that has already been covered a few times here), but more about what the readers and the critics

@Mendez196

Load Full 4 Comments

: Have there been any studies indicating which software documentation practices save the most time during onboarding? It's generally conceded that at least some documentation saves people time when

: Re: Bridging the gap between colloquial usage and technical meaning of terms Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general

More posts by @Mendez196

: How to create tension during a conversation In my novel my protagonist speaks to a man while being held at gun point. She (protagonist) tried to kill him. He was her boss, was involved in

: What does "juvenile tone" mean? I often hear the word thrown around, but I don't have any idea of what it is, or how can it be avoided. So, what does "juvenile tone" mean and how can I

: How can a "rip-off" still be good? This time, I'm not really talking about the legal side (that has already been covered a few times here), but more about what the readers and the critics

: Have there been any studies indicating which software documentation practices save the most time during onboarding? It's generally conceded that at least some documentation saves people time when

Login to post a comment!

0 Comments

Back to top