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.
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.