Wednesday, September 19, 2018

Use The Same Name For The Same Concept

Maintain style (Posted by Jerry Yoakum)


Technical documentation must always use the same words to refer to the same concept and the same sentence structure for similar messages. To do otherwise could confuse the reader, causing the reader to spend time trying to determine if there was a technical message in the rewording itself.

For example,
There are three types of special commands. Regular commands come in four varieties.
is not as good as:
There are three types of special commands. There are four types of regular commands.


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.