7 Most Common Issues When Writing Documentation

7 Most Common Issues When Writing Documentation

And how you can prevent them from happening

Good documentation is a crucial asset for any software. It helps its users and developers understand how things work exactly. Based on its goal, documentation consists of different types of content. Especially developing good documentation is critical for developer relations engineers. It is a tool to make developers clearly understand the technology they will use.

The research article Software Documentation Unveiled presents an empirical study on documentation issues based on information from 878 documentation-related artifacts such as mailing lists, Stack Overflow discussions, issue repositories, and pull requests. The study based on these artifacts formulates a detailed documentation taxonomy by addressing documentation issues with 'what' and 'how' the content is written and organized in the documentation.

Issues with HOW the content is written and organized in documentation

According to the empirical study, many problems have arisen from how the content is written and organized in the documentation. Such problems include readability, usability, usefulness, and maintainability. This section describes each problem and provides suggestions on how to prevent them.

2.png

Readability

Readability indicates how easily documentation can be read and understood by readers. Some documentations are hard to read and understand, causing poor readability. The lack of clarity or confusing information is the main issue that results in poor readability. Another reason for poor readability is having too much technical jargon and including verbose/noisy content. Such readability issues confuse average users, and they may never use the documentation for any purpose. It is even worse when the users have only limited time to go through and understand the documentation. Sometimes less is more.

Usability

The usability of documentation shows how much it helps to achieve the users’ objectives effectively. Even Though documentation contains all the required information, if they cannot easily find the information they need, it is not good documentation and badly affects the user experience. The research revealed that half of the usability issues (50%) stemmed from difficulties finding the readers' needed information. Information organization is the second issue that causes poor usability. Users find it difficult to retrieve the information in such disorganized documents in one try. Still, they often search through the code more than once, which wastes their valuable time. And time is most likely limited at a hackathon or a time-sensitive project.

Usefulness

There is no point in maintaining documentation if it does not contain useful information for the reader. According to the study, bad documentation often contains unnecessary data, unrealistic code examples, and irrelevant images and content. If the documentation does not help readers achieve their goals, it is not useful for them. The research study has revealed that several factors impact usefulness. For example, containing unrealistic code examples may help with understanding the concepts, but it will never help to apply them to a more realistic scenario. Users for feedback on the documentation will be a good solution to mitigate the lack of usefulness.

Maintainability

Maintainability of documentation refers to how easy it is to apply changes or corrections to it. Document maintainability issues are another prevalent issue in documentation. Many of the maintainability issues come from duplicates which are hard to avoid. It is not easy to introduce changes to such documentation without impacting many parts of the existing version of it. Re-iterating the same thing repeatedly does not add any extra value to the reader but wastes important document space. Another common reason for poor maintainability has redundant files, which can confuse the users on which file they need to refer to.

Prevent the how issues

According to this empirical study, most documentation issues related to their usability come from poor content organization and poor information findability. These issues can be prevented by embracing a consistent documentation format, offering the users a search engine to quickly find the content they need, archiving the old versions of the documentation in a specific location, and investigating user documentation needs. The study also proposed applying code clone detection techniques to detect documentation clones and automatically remove them to reduce redundancy in the documentation. In addition, these issues can be mitigated by conducting studies to investigate the users’ behavior when looking for documentation for defining better documentation practices and presentation. Following are some suggestions on improving the content organization and how the content should be written.

Documentation should be clear, concise, and persuade readers

One of the most important things you should follow is keeping the documentation as clear and concise as possible. Avoid unnecessary long paragraphs to help the readers easily search for the information they want.

Make it skimmable

A skimmable document helps readers quickly grasp the overall intention or meaning of the content just by skimming through any part of the document. They can quickly skim over and find out the relevant information they need without reading the whole content. For example, good documentation uses tactics to make it more skimmable such as keeping the headings and sub-headings descriptive and concise, using bulleted lists and summaries, and using descriptive hyperlinks, etc. bad documentation lacks clear heading structure a content flow throughout the document.

Enable providing feedback for the documentation

If you want to improve your documentation, the best practice is to have some room for user feedback. You can share the documentation before its publication with other stakeholders and hear their opinions. Incorporate those changes to improve the documentation content, structure, and more.

Allow readers to navigate and search for content they want easily

Another best practice is making the documentation easily navigable and searchable without any hassle to the readers. For example, good documentation contains basic search functionality that helps readers search the relevant information using keywords. The more advanced the search functionality, the better. Also, good documentation contains quick links to other chapters and backlinks to previously navigated content so that users can quickly jump back and forth to the relevant information while going through the current content. Bad documentation typically does not contain even the basic search and does not contain quick navigation options.

Issues with WHAT is written in documentation

Correctness, completeness, and Up-To-Dateness are the major reasons for this problem. This section describes each issue and describes how to prevent them.

3.png

Correctness

Correctness of documentation shows how accurate the information it contains is. Documentation with high accuracy justifies the information contained in it. Inaccurate documentation, on the other hand, makes developers valuable time wasted. Suppose a technical document contains a code example that has bugs or errors and doesn’t work as explained. In that case, developers who may try to replicate the code example with errors will ultimately end up with nothing but wasted time.

This research study reveals that incorrect code examples are the majority of cases of bad code. Also, content accuracy issues can be caused by an inaccurate translation, leading developers in different countries to misinterpret the information.

Completeness

Complete documentation consists of all the information about the system for users to interact with it without any issues. The incompleteness is another severe issue associated with bad documentation. Incompleteness is the cause for more than half of the issues related to the documentation content. This study revealed that the types of documentation mostly affected by incompleteness are the API references and code comments. There are different causes of incompleteness. One major cause is having definitions of ambiguous terms. For example, some technical product guides may contain specific technical terms but lack their definition, leaving users unable to use the product. Also, incompleteness can cause missing information, such as software products or key technical information can be missing to complete the development.

Up-To-Dateness

An outdated document does not reflect the exact current behavior of a system. About 39% of issues related to documentation content are related to outdated information about the system. In most cases, this issue reflects when the software behaves differently than described in the documentation, which can stem from code changes requiring document modifications. Some technical documentation consists of outdated code, creating inconsistencies with other code examples. Another major cause of this problem is referring to deprecated information like outdated copyright information, version numbers, and outdated references.

Prevent the what issues

Code examples are the most common documentation type impacted by correctness issues. To prevent these issues, applying testing techniques on code examples is a good approach. The study suggests to include developing techniques to test code examples in the documentation, validating the consistency between code examples and the actual source code, performing regression testing on code examples, and automatically generating code examples to be included in the documentation.

Make it comprehensive

A document must be comprehensive. In other words, it should contain every possible information that helps readers understand its purpose. For example, if it is technical documentation that includes software usage, include everything related to installing it, like how to install it in different operating systems. If there are technical terms, explain them in simple terms. Bad documentation with incomprehensive content leaves the readers with ambiguous situations. Therefore, with complete documentation, you can eliminate such inconveniences.

Keep the documentation up-to-date

As described above, some documentations need to be regularly updated, which leads to contradictions between the actual behavior of the system with what is described in the documentation. Good documentation is always up-to-date and reflects the exact behavior of the system at the moment. Since this is a bit challenging in software systems that get regularly updated, keep a dedicated staff to update it or make documentation update part of your development teams’ tasks.

Make everyone involved in the documentation process

Documentation is not an effort of one particular person, but it is often an effort of a collection of people working on different parts of the software application. From end-users to stakeholders, including everyone in the documentation process so they can contribute to the completeness of the documentation. You can incorporate this process into the development workflow to keep the documentation regularly updated while breaking the silos between different teams involved in creating and maintaining the documentation.

Conclusion

Good documentation has a direct impact on user satisfaction and developer experience. As described in this article, several issues are associated with bad documentation. The worst issues related to documentation include lack of readability, usability, correctness, completeness, and readability. There are several ways to avoid such mistakes and improve documentation quality. For example, embracing a consistent documentation format, offering the users a search engine, developing techniques to test code examples in the documentation, validating the consistency between code examples and the actual source code, performing regression testing on code examples, and automatically generating code examples, etc. Good documentation ultimately becomes a good knowledge base and companion to developers, end-users, and other stakeholders.