4 ms·
> 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 f
by KineticLensman 5y ago
> 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.
- erwincoumans 5y agoTake 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).
- KineticLensman 5y ago> 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.
- deleted 5y ago[deleted]
- deleted 5y ago[deleted]