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!

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 id and the serial_number. Which one should be used to identify a device? Why can't we just have one?

• Does manufacturer refer to the Trade name or the Legal 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 name and display_name? Why do we need the attribute name if we can already identify a device by its id?

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.

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.