Bad Documentation, Bad Documentation

Inadequate documentation saps productivity, can cause chaos both internally and, for the end user, and will almost certainly doom an otherwise solid software project to failure. The chaos bad documentation engenders is multifold, ranging from the inability to find fixes when the docs are outdated to just getting the software tool or platform to work without significant trial-and-error testing.

At the root of the problem is how humans are notoriously bad at preserving data and how-to steps when they build something and offer it to users.

As Kelsey Hightower emphasizes in the introduction of “Docs for Developers” that we cited in the previous article: “If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite,” Hightower writes.

In this article, we describe examples of bad documentation. But not to be too negative, we also offer fixes that are accessible for almost any organization.

Difficult to Understand

Documentation is essential. Not done reading right, and the loss in productivity becomes very expensive. @aburke626 @Amazee #KubeCon2023 pic.twitter.com/b9RVM9Qutr

— BC Gain (@bcamerongain) April 19, 2023

Firstly, good documentation is easily understandable and devoid of excessive jargon and intricate language. It maintains simplicity and conciseness, directly conveying the essential information.

The documentation should not be burdened with lengthy narratives before imparting instructions or relevant details, Alanna Burke, open source build and deploy platform Lagoon community manager and developer relations advocate, said. Consequently, if the documentation is arduous to interpret, it won’t captivate readers as effectively as meticulously designed and presented documentation does, she said.

Making something easy to understand is more than language — it’s also about consistency, using common terminology across and among product so that users can find what they need even when using a new product within the company’s product offerings.

“In addition, documentation is typically accessed from a search engine, so the page into which a user lands needs to provide context for the user to identify whether they’re on the right page, what other content might help them, what related content might be relevant and whether they’ve landed on step 2 of a five-step process, for example,” Fiona Peers Artiaga, director of documentation and technical writing at Grafana Labs, said.

Inaccurate

Inaccurate documentation is highly undesirable, obviously. Documentation that is out of date is also inaccurate.  Reliable documentation attributes its authorship and creation date, Burke said. This empowers the identification of inaccuracies and their origins. Also, the age of the documentation aids in addressing errors encountered.

Obviously, technical accuracy is “job one,” Artiaga said. However, while the last updated date is valuable, the author attributions are less important, especially as so much documentation is built collaboratively so there’s more than one author, Artiaga noted.

Poorly Designed Visuals

In “Visualizing Data,” by renowned designer Ben Frey, seven stages of creating an information visualization are identified: acquire, parse, filter, mine, represent, refine and interact. This all requires work, of course. But once these stages are completed, the work is ongoing — users will certainly stumble if the visuals are not kept up to date.

“The most common problem with visuals like screenshots or charts is that they can become out of date, and are usually more difficult to update,” Burke said. “Reliance on visuals also reduces the accessibility of your documentation to those with vision issues.”

Indeed, regularly reviewing and updating extensive documentation is demanding. Often, it necessitates consultations with numerous individuals to verify information. Imagine having a veteran of 50 years in-house who comprehends all procedures and can explain and clearly illustrate them with quality text and visuals. This is what documentation should offer.

The hard part is building a culture so that documentation is part of the definition of ‘done,’ so docs get updated when new code or updated code is pushed, Artiaga said. “Technical writers are key to a culture of agreeing that documentation is a first-class citizen. Technical writers are particularly valuable as the first user and asking informed questions to ensure that when the code is ready, the aligned docs are also ready,” Artiaga said. “This leads to better user experience, stronger enablement, and higher rates of adoption. The technical writer looks at the comprehensiveness and comprehensibility of the source documentation to ensure users have the content they need.”

No One Owns It

The challenge of shared responsibility for docs often arises. People frequently claim time limitations and lack incentives. If your responsibilities are confined to the deliverables, why burden yourself with extra tasks, Burke asks rhetorically? For many of the technical folks who lack experience in writing, technical documentation or proficient writing feels beyond their capabilities, Burke says.

Bureaucratic obstacles are also common. When documentation lacks priority as a deliverable, demands for it intensify without granting additional time. Problems can emerge, ensnaring everyone, Burke says.

However, it is important to be realistic about what to expect from outside contributors. We find contributors sometimes shy away from contributing because they are blocked by knowing how to contribute, Artiaga said. “That’s why we built our Writers’ Toolkit — The goal of guidelines is to provide a set of approaches that remove the cognitive work for ‘how do I tell users about this,'” Artiaga said. “But it does require more than simply reference material, which is insufficient for user success as we grow in maturity in our market. Without tasks (how) and concepts (what), users struggle to be successful.”

The Code Is Considered Self-Explanatory

These are prevalent justifications leading to poor documentation. The belief that code is self-explanatory is widely known, for example. Yet, retaining this assumption can disrupt development timelines.

“Readable code and user documentation just aren’t the same thing. I’m sure Facebook has a very nice code base, but I wouldn’t go looking there for help with my profile security settings, right?” Burke said.

Indeed, the assumption that code is self-explanatory may apply to the developer, relying on the code to serve as documentation can alienate many potential users who require more in-depth explanations and how-to steps.

“If a project is seeking a more mature audience or wider adoption, then documentation investment is paramount. Developers are very good at reading code, for sure. But as the project grows in the market, the audience seeking information grows also,” Artiaga said. “As a result, good developer documentation along with good conceptual information and clear task-based content becomes critical to wider growth.”

Artiaga also does not agree that documentation categorically disrupts development timelines — in fact, a shared understanding of the code, because it is documented, can spur development and ensure better asynchronous communication and understanding, she said. “In short, good docs can speed up development,” Artiaga said. “Embedding a technical writer into the development team ensures that there’s a common understanding of what the project is accomplishing and how.”

To tackle this, Burke noted how Google adopted a distinct strategy. They substantially revised existing conventions. Engineers’ documentation was significantly streamlined using a system Google dubbed as g3docs. This system enforced standardized documentation practices. Documentation was integrated within source code, leveraging Markdown.

This enabled engineers to seamlessly fuse documentation tasks with coding responsibilities. The system automatically transformed Markdown content into refined HTML pages. Collaboration played a crucial role. Google partnered with influential engineers to introduce this system and closely collaborated with specific teams to ensure uniform acceptance. Transparency was maintained through open iterations. However, teams weren’t compelled to comply; they were inspired by successful instances. This method engaged key personnel and led to widespread adoption.

👁 Image

Burke offers the following tips:

• –To assign responsibility, designate a manager for documentation. Even if not their sole task, make it their official role. This person also crafts templates, training and support.
• –Begin with standardization. Set tools, style guide, and approval process. Clarify documentation’s journey, regeneration, and spell-checking. This eases anxieties and maintains upkeep. Define review frequency and responsible parties.

Lest we forget, the user usually doesn’t care about judging the quality of the documentation. They want whatever they are using the software tool or platform to just run seamlessly. In the case they need to install or run other tools to get started, they want precise information about how to do that, as opposed to a link that leads to a rabbit hole of having to learn to install another tool or platform. The user also certainly does not want to have to engage with the software provider’s help.

“Users prefer not to engage in direct conversations with us,” CEO and co-founder of Shauli Rozen of security provider and open source Kubescape creator ARMO, said.

Some users might request an onboarding session, while most prefer self-service with “zero touch,”  Rozen said. “They are like ‘just provide me with your documentation to read and review the code, and give us a link. If I’m unable to do it independently, then I won’t use the software’ — it’s as straightforward as that.”

Hightower, for example, realized this myself when introducing new developers to Kubernetes.

“Developers wanted to know how all the pieces of Kubernetes fit together, but there wasn’t any content that helped them,” Hightower said. “I found out quickly that you have about five minutes to help developers find the information they need before they abandon your project and move on to something else.”