“Redundancy Clarifies Meaning”
By Robert Delwood, a Lead API documentation writer
“Redundancy Clarifies Meaning” is one of those phrases that is not well understood, and is less well received. In technical writing, it’s always thought of as repeating text. Having the same text in several places means it must be updated in several places, which is a thing to be avoided.
But that’s not the concept here. It’s more that information supports each other and that nothing is contradictory. In a simple example, it’s referring to a Create button during a discussion about creating something. That makes perfect sense. On the other hand, if the creation discussion refers to selecting the Override button, that confuses the reader. Even if it was the correct procedure, something needs to change to make the reader comfortable. Likely, renaming to button to Create. Then, the two concepts match with redundance: The text discusses creating something, and the action selects a button named Create. That match can be thought of as peace of mind. The reader knows what to do, what to expect, and is confident it’s the correct action.
The same holds true within API documentation writing. Everything should match. The text should match the examples, which should match the screenshots. Consider the example below. There are several mistakes.
- The field is referred to as both storageMode and storage_mode, which is inconsistent parameter casing.
- It’s listed as an object but the example shows an array (indicated by the hard bracket).
- The field storageLimits is noted as an integer but one of the examples is a string.
There’s a fourth casualty, too. The reader loses trust in the documentation and the company. And why not? This example shows little attention or concern for detail, so why would the coding be any better?