Rid Your API Documentation of Non-information

Create accurate, clear, concise, and focused docs without unnecessary verbosity

Developers dislike documentation for various reasons, one of which is the presence of non-information — unnecessary verbosity — or extra words that do not contribute value or clarity to the docs. The presence of uninformative information adds to the cognitive load — the mental energy or strain required to process and understand information or perform a task.

API Docs that include unneeded information can introduce mental friction that results in an interruption (the developer gets frustrated and leaves the documentation portal searching for a less mentally-taxing source of information).

Photo: Erio Noen

What type of non-information are we talking about?

Many professional developers are hindered by “boilerplate documentation that merely rehashes the name of the API method, bloats the presentation with derived information such as inherited members, or provides overly trivial examples,” observed researchers Walid Maalej and Martin P. Robillard. Documentation quality can be improved by detecting and removing non-information from API Docs.

⦾ Advice: Avoid the use of filler words, redundant phrases, or excessive elaboration without adding meaningful information. Use authoring assistance tools that can help you reduce verbosity and increase clarity and comprehension.

Non-information is unnecessary and can make your documentation challenging to read, comprehend, and navigate, potentially leading to information overload and making it more challenging for developers to extract the essential details they need from the documentation.