In a previous article, we discussed Design by Contract and how high-quality API documentation can greatly enhance understanding and improve user productivity.
Let's quickly explore some of the most overlooked resources that programmers often miss, and how small improvements in documentation do greatly enhance the user experience.
Write poor documentation and feel the frustration
Today, we are developing a thrilling new API to register IoT devices in a database. Let's see how small changes in documentation that programmers usually overlook can incredibly improve the user experience.
At some point in our developer careers, we've all written this wonderfully surprising documentation. Yes, you too!
| Attribute | Description | Example |
id | Device ID | 10034 |
manufacturer | Name of the manufacturer | IoTDevices S.L. |
serial_number | Serial number of the device | G2J39Z26DH |
name | Device name | light_intensity_sensor_rooftop |
display_name | Device display name | Light intensity sensor at Rooftop |
This description is not more useful than the attribute name itself, as it does not clarify the context or the intention that the developer assumed was obvious.
Here are just a few reasonable questions that API users lacking the context of the API will certainly have:
There are two unique identifiers, the
idand theserial_number. Which one should be used to identify a device? Why can't we just have one?Does
manufacturerrefer to theTrade nameor theLegal business name? In other words, which teams can use the value of this attribute? (Legal, Billing, Marketing, Frontend, etc.)What are the intended uses of
nameanddisplay_name? Why do we need the attributenameif we can already identify a device by itsid?
Poor documentation causes many problems for end users. Users have to guess the meanings and uses of attributes by reading the code. Also, low-quality documentation leads to inconsistent usage of these attributes, especially in large codebases. Eventually, team members interrupt each other to ask for help, overall productivity slows down, and code quality decreases.
Write great documentation and feel the appreciation
Users need to understand the details and meanings of attributes that might not be clear from the code. A good description adds value and clarity. In reference material, descriptions should be as clear and specific as possible, using concise and straightforward language.
Here’s an improved version of the documentation. In bold, you'll find the answers to the previous questions.
| Argument | Description | Example |
id | A unique identifier generated by the creation function. It is unique across all IoT devices in our company. | 10034 |
manufacturer | The human-readable commercial name of the company that produced the device. | IoT King |
serial_number | A unique identifier assigned to the device by the manufacturer. It is unique across all IoT devices of a manufacturer. Although improbable, two devices from different manufacturers may have the same serial number. | G2J39Z26DH |
name | The human-readable name of the device in English. Intended for internal use only in APIs and monitoring services. The use of name is preferable in these cases, as the resource is easier to identify compared to the id. | light_intensity_sensor_rooftop |
display_name | The human-readable name of the device, chosen by the end user. Since it is set by the user, it may be written in any language. The intended use is to show the display_name of the device to the end users in frontend apps, such as web and mobile apps. | Light intensity sensor at Rooftop |
This description provides clear and detailed information about the attributes and how to use them. It makes it much more likely that both new and experienced users will understand and use the attributes correctly in new projects. As a result, developers and users feel more efficient and independent. Code quality improves, and productivity goes up again!
Resources and attributions
This article was heavily inspired by Creating Effective Documentation for Developers (LFC112) from the Linux Foundation Training.
If you really enjoy writing clear technical documentation, you might consider becoming a professional Technical Writer for companies, open source projects, etc.