3 ms·
Some sins of technical writing: Undefined/vague abstractions or methaphors: Leave the meaning of notoriously overloaded terms like component, plugin, container
by rwoerz 3y ago
Some sins of technical writing:
Undefined/vague abstractions or methaphors: Leave the meaning of notoriously overloaded terms like component, plugin, container etc. unexplained in your specific context of writing.
Homonyms: One term has several meanings. E.g., "server" is either a machine or a OS process.
Synonyms: One meaning has several terms. E.g., "module" and "project" in Maven.
No examples: Only rely on the reader ability to interpret pure abstractions instead of giving him/her examples to abstract from. E.g., provide only the EBNF of a certain language.
- KineticLensman 3y agoOne that annoys me is when authors use multiple different terms for the same thing. In fiction, variety can be excellent, but in technical writing, it really adds to the readers' workload. I remember reviewing a doc where, depending on which section you were reading, the terms 'design', 'architecture' 'system' and IIRC 'component framework' were used interchangeably. This made following the reasoning hard because the doc was itself a review of two distinct technical solutions. This often happens when a doc has multiple authors and no global consistency checking.