08 September 2019

The perils of descriptive terms in technical documentation

Yesterday I was reminded of why it is a bad idea to use adjectives or specific direction information in technical documentation. I was walking down a street I know well when I came across the sign shown bolted to a lamppost. The somewhat dishevelled appearance of this "new" piece of information disguised the fact that the roundabout in question has been there for several years.

So why is the sign a bad way of providing the information required, and what would I do differently?

Using Adjectives

Using descriptive adjectives in technical documentation is a big no-no. For a start they are subjective. Whether it is the "square select button" or "large save icon", both "square" and "large" are redundant unless there are two select buttons or save icons. If there are, that's arguably a bad UI and should be redesigned to remove the duplication. 

In the sign in question, my problem is the use of the adjective "new". Yes the sign and the accompanying roundabout were new at some point, but clearly not now. It is difficult to pinpoint at what time the roundabout stopped being new, but that also makes for bad technical information. If the information provided isn't precise, it is open to interpretation and means confusion and potential mistakes.

The use of adjectives also means a higher cost to serve in maintaining the documentation. If you have to amend the information at some point in the future to remove the word "new", it increases the cost of production in time and effort.

Finally, the word "new" doesn't add anything to the important information. The fact that the roundabout is there at all, is all any motorist needs to know. Whether it is new or old is neither here nor there.

Using Directional Information

There are those that suggest that having to provide instructions on finding the necessary information to perform a function, means it is badly designed. If it isn't obvious where a UI element is, you should be working with your UI Designer to change it.

In the sign shown, it is the use of the adverb "ahead" that is the issue. The sign is facing the direction of travel, so naturally the roundabout is ahead of the sign. If it wasn't, there'd be no need for the sign at all. 

Here's another example: "Click on the Select button to the right of the Category field."

Again the specific mention of a location makes for a higher cost to serve, because of the cost of amending the sentence in the event that the UI changes. It also means changes could be required for UI localization. For example, if the UI changes from a dialog with fields going left to right to fields going right to left.

Other Potential Mistakes

Although it doesn't apply to the sign shown, I also avoid using numbers when describing UI elements. Take the following example: "Select one of the following three values from the Categories drop down field to describe the entered information".

Whilst there is nothing seriously wrong with this information, it is inefficient. If the number of available categories changes, not only would you have to amend the list of category values, but you'd have to amend the number "three". This may not seem like a big deal, but it can be easy to miss that word and only amend the list items. The same applies to the use of the number "one". Should a change be made to allow more than one category, a documentation change is also required.

So would you use "Select the categories from the drop down field"? Perhaps, but there could be still more redundant information. Is it obvious to the user that they have to select something from the drop down? If so, you could reduce the text to "Select the required categories to describe the entered information". You could reduce the help further if the users know why there's a need to enter one or more category. If this is the case, you could reduce the text to, "Select the required categories".

What this perfectly highlights is the need to know your audience. If you don't, you won't be able to answer the questions above.

Summary

So how would I word this sign? I wouldn't have one at all. Why? If you remove the words "new" and "ahead" you're only left with "roundabout" which on its own doesn't add anything. Secondly there is a standard roundabout warning sign some 10 meters beyond the sign.

No comments:

Post a comment