Two Words API Documentation Writers Should Never Use
By Robert Delwood, a lead API documentation writer
“Words mean things and technical words mean technical things.”
I say this a lot to remind us that we have words for a reason. If the first rule is that they have meaning, the second rule is to make every word count. That is, too few words, and meaning is lost. But too many words may also lose meaning, or at least, convolutes meaning. Either case is a sin in API documentation writing. Two words that are misused so often, it’s best to just never use them: Random and unique.
Random
Few things in the REST world are random. In fact, that would often defeat the purpose. One common example is that some refer to GUIDs as random. They are funny-looking numbers, like:
4e5914bd-8d10–407a-96dc-a6e8804d2752
A GUID (globally unique identifier), also called a UUID (universally unique identifier), is a 128-bit integer used to identify resources. They were designed to create identifiers and are far from random. There is a precise calculation involved with generating them. The bottom line? Don’t use the term random. It’s usually wrong.
Unique
This is a great case showing that while a statement can be absolutely true, it’s also absolutely meaningless. First, the term is overused, even if accurate. Whenever a writer can’t think of a more descriptive definition of a field, they say something like “Specifies a unique identifier for the object.” The problem is, unique doesn’t add any meaning. The object has to be identified by that value and the programmer has no control over that. For example, when an object is first created, the request typically returns an Id, perhaps as a productId or processId. For the rest of the time, the programmer must use that value to refer to it. Whether or not the value is unique just doesn’t matter. Because it just doesn’t matter, it doesn’t need to be in the description. “Specifies an identifier for the object.” is fine, conveys the same meaning, and keeps the word economy.
Conclusion
Make every word count, or put another way, make every word carry its weight. A simple test is to remove the word and if the sentence still says what it needs to say, the word is superfluous. They are always exceptions to random and unique, true, but as a best practice avoid using them. Then, they must prove they’re needed.