I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes:
When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it to "load" in the middle of a sentence. People will waste time wondering if it's the same concept or subtly different.
This is the opposite of what we've been taught at school (avoid repetition! use synonyms!), so it takes a bit of discipline to follow it.
This is not just for technical writing and coding. It goes for communication and thinking in a technical context as well. You're going to make so many design mistakes if you use several words for one concept, or the same word for multiple concepts.
I know the Sapir-Whorf hypothesis is discounted by linguists, but I believe I have loads of first-hand experience showing how word choice affects design decisions in fairly strong ways.
And that shouldn't really be surprising. We're not discussing things we can plop down on the table in front of us. We're discussing abstractions. We're discussing machines of the imagination. The only way we can construct them in each other's minds is by putting words together in the right sequence. Obviously, the choice of words are going to affect how people picture these machines in their heads.
We cannot be careful enough with the language we use when we try to build complex things.
I know it’s not the point of your comment, but the Sapir-Whorf hypothesis is about how your language itself structures your thinking, not word or grammar choice in individual utterances or writings made by an individual.
Not quite. Sapir-Whorf is specifically about the _structure_ of a language, meaning its syntax, morphology, etc.
Vocabulary choice obviously influences how you interpret a specific utterance, but Sapir-Whorf is about how a language's structure influences its speakers' cognition at a basic level, i.e. _how_ they think, not _what_ they think.
This applies quite generically to coaching as well: if the person you're listening to uses a certain word to describe something, continue to use that word yourself instead of trying to paraphrase it.
In that sense, you're sticking to one word for a concept, but the word is given to you by someone else. And by using their terminology and not your own refactoring, you are making sure that you're not distracting them from their own thinking.
> When writing a technical document, stick to one word per concept
Yes, this is absolutely critical. As a tech reviewer I once came across a doc that used no fewer than seven different terms for the same underlying thing. Part of the problem was that it has been written by at least two authors over a couple of months. At least one of the authors admitted that they hadn't take the time to remind themselves what had already been written.
In non-fiction, it can be good to introduce variety, and challenge the reader But as a tech author, if the reader has to work to keep track of things through a doc, simply because you have been lazy to check for consistency, you have failed.
[Edit] There are a couple of things that can help avoid the problem. The most important is to have a final step that involves consistency checking. Where I used to work, we encouraged a peer-review step before docs where submitted for formal tech review. This significantly reduced the workload on the formal reviewers.
Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).
> Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept
Good point! I'm guilty of the problem myself. I did mean tech docs as a subset of non-fiction. In these terms, I would now state that technical docs should use 'one term per concept', but that non-fiction doesn't have to as long as some ambiguity is acceptable.
> This is the opposite of what we've been taught at school
Not exactly. Schools don't tend to teach this concept, but there is a difference between
• regular "words" — which are only defined descriptively by anthropological observation of usage; whose usage and shades of meaning evolve memetically; which can have different shades of meaning to different people; where people using a word in a novel way can't really be said to be using it "wrong", only "unclearly" — and not even that, if their usage later catches on;
• and jargon terms — which are defined prescriptively in some originating document somewhere; where jargon can be used "correctly" or "incorrectly"; where everybody attempting to "properly" use a given jargon term is trying to convey exactly the same meaning from the originating document's prescriptive definition.
Jargon terms aren't specific to technical writing; they're quite common in everyday prose as well. For example, units of measure are jargon terms. You would never even think to try coming up with a synonym for "degrees Celcius" or "US Dollars" if you wrote it several times. You'd at most abbreviate these, or leave them off of successive entries in a list of same-united things.
The key realization of technical writing is that you yourself can create jargon terms — define them just for the purposes of your document; and that it's extremely helpful to readers' understanding of an opaque subject when you do so, because you're making it clear by doing so that this is (at least in your own presented mental model) a distinct important concept to be lifted out and thought about on its own, a proposed new mental tool in the reader's toolbox for dealing with the problem domain.
Yes! This annoyed me for so long, and I only recently learned that it happens (in part) because non-technical writing strongly encourages so-called “elegant variation”[1]:
Unfortunately, elegant variation spills over into “non-technical” cases were technical precision is still important, and that becomes a problem — like if you’re whether you’re supposed to know that the Pope is the same as the Bishop of Rome.
[1] Great quote from the article about the absurdities that the practice introduces:
>>A humorist imagined writing a news article about Gaston Defferre: "It's OK to say Defferre once, but not twice. So next you say the Mayor of Marseille. Then, the Minister of Planning. Then, the husband of Edmonde. Then, Gaston. Then, Gastounet and then ... · Well, then you stop talking about him because you don't know what to call him next."
Very good advice. I guess the "side effect" of using the same word everywhere is pointless in a technical context; nobody worries about their technical writings being "boring" or repetitive...
Another thing that annoyed me in tech writing when I was still fresh in the field was when all the examples built upon the previous and then out of nowhere the next example was different. IE: some author has spent a couple chapters building up, I dunno, some coffee shop website but now that they want to discuss concurrency they're going to switch to a CLI app that hits Wx sites for the current weather.
>When writing a technical document, stick to one word per concept
The problem comes since this doesn't make it seem like you have a wide vocabulary. A large vocabulary is naively indicative of intelligence; why you'll see inexperienced people using flowery complex language in a multitude of different ways to explain the same ideas..... Certainly proliferated from American English. Annoying.
Interesting. I’m guilty of this in my online writing in the name of SEO. After all, my readers might search for either term. This probably makes my writing worse.
When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it to "load" in the middle of a sentence. People will waste time wondering if it's the same concept or subtly different.
This is the opposite of what we've been taught at school (avoid repetition! use synonyms!), so it takes a bit of discipline to follow it.