Why content quality matters
The quality of your organization's technical documentation is more critical than ever. In my experience, potential customers carefully evaluate technical documentation before purchasing. Whether an IT professional evaluating an enterprise application, a developer implementing an API, or a consumer using a product, they're reading your content to learn about the product and how to use it.
If prospective customers cannot find high-quality technical or user documentation to support their purchase decisions, you may never have a chance to close the deal.
- Good informational content helps prospects become customers. They want to understand your capabilities and unique value. However, this type of content falls more into the hands of Marketing and Sales. It's the bait on the hook, so to speak.
- Good instructional content and technical documentation help customers remain customers. They need fast, effective service. Organizing content around user roles and activities empowers them rather than frustrates them. Plus, it's integral to customer support, branding, and trust. If it's not there for them, they start looking for alternatives.
This article provides information on content quality problems and ways to course-correct to create a good user experience when they use your product or service.
Costs and risks of content quality problems
Several dimensions make up good technical documentation:
- Can the reader find it and understand it?
- Is the content complete and accurate?
- Is there consistent use of product branding and industry terminology?
We can break these down further, but we'll stick with this high-level list for this article.
Findable
Today, it's more important to be able to search the content. Technical documentation has evolved over the past decade, and it's primarily in an online help format with an option to download a PDF version. With that said, SEO in technical documentation helps search engines respond with the most relevant content.
An excellent example of SEO in technical documentation comes from Microsoft. In their content, on docs.microsoft.com, the description metadata field is required. It must follow Microsoft's SEO writing guidelines for its content contributors.
If you're unfamiliar with the example below, Microsoft develops its technical content using markdown in the Docfx docs-as-code framework.
---
title: Manage Azure portal settings and preferences
description: Learn how to change Azure portal settings such as default subscription or directory, timeouts, menu mode, contrast, theme, notifications, language or region, and more.
date: 08/10/2021
topic: how-to
---
Accurate and complete
Technical documentation is living content continuously updating as new features are released, or operational processes change. Because of this, it must review for accuracy and completeness. Is the expected behavior of the product feature accurately described? Are the procedural steps accurate and complete?
Accurate and complete means the user accomplished what they set out to do because the information was in the documentation. However, they're at a dead-end and left to call support if it's not there.
Consistent
If your company has a valuable brand, you'll suffer a tangible loss if branding isn't used consistently. Inconsistencies can confuse users or affect the company's brand. For example, the user might be confused about which content is correct, mainly if your content uses several terms interchangeably. In addition, the translations by human and machine translators can contain these inconsistencies if your content is localized.
Understandable
Even if the content is accurate, complete, and consistent, it might not be understood. This is because so many factors come into play when we talk about whether someone understands it or not:
- Sentence structure: Does the sentence articulate the idea clearly and directly? Is the sentence so long it's too difficult to follow? Is the sentence too convoluted to understand? Does the sentence include information that adds nothing but confusion?
- Vocabulary: Does the user understand the words? Is your content translated?
- Terminology: Are the terms used correctly and consistently throughout the documentation?
- Spelling and grammar: Does the content contain relatively simple errors that distract, confuse, or mislead your readers?
Where content quality problems come from
Content quality problems can come from different areas. The top problem I've observed is that the user is misunderstood—that is, the overall user journey is overlooked. For example, IT professionals and developers are often misunderstood, so their content doesn't directly speak to them. What do I mean by this? Most often, the content is written by a very technical person, and then it's handed off for editing and formatting. There's rarely a discussion among the cross-functional teams on use cases or scenarios for the flow of the content, which would give the user what they need when needed.
I use the IT professional as an example because they have a hard job. Not one company has the same IT infrastructure implemented. Plus, there's a lot on their plate with supporting different operating systems, versions of applications, security and preventing intrusions, user administration, and evaluating solutions. Because of this, I have found that writing content for them works best in a scenario or goal-based format. The IT professional consults technical documentation for a reason: to get answers to their questions or implement an enterprise solution end-to-end. This format results in giving them what they need when they need it.
A survey by author and content strategist Rachel McConnel clearly recognized how quality content adds value. However, this survey also recognized the adverse business impact of letting just anyone create the content. But at the moment, it's still a blind spot for some organizations.
Ways to design and develop better content
In addition to the dimensions of good technical documentation mentioned earlier, you'll want to understand the user journey by "designing the content." Content design helps you develop better content by answering a user's need in the best way to consume it. Sarah Winters states in her book that content design is "…about using data and evidence to give the user what they need, at the time they need it and in a way they expect it."
Content design is not just writing. It's a way of thinking. It's collaborating with cross-functional teams like UX, product owners, and engineers to find the best solutions to give the user what they need when they need it and how they expect it. For example, the content could be a one-pager, a complete user guide, a training module, etc. It could even be as small as UX/in-platform microcopy.
The basic principle here is that the user's needs come first, then the format. You're creating content that helps create a good experience for the user when using your product or service. You're helping them along their journey!
- User needs come first: Research your user's wants and needs. It can be user research, usability research, industry research, expert research, or any kind of research with data and evidence of what the user wants and needs.
- Give them what they need when they need it: We know that giving people information too early or in the wrong place can make people leave in frustration and no longer trust you. Understanding what your user needs – when they need it – can be the difference between success and failure.
- In the way they expect it: Use your users' language. You don't use language for search engines – you use it for the humans behind those engines. You don't pull people into useless search results. Instead, you help people. The language used in a product must reflect your user's vocabulary, or they may find the interaction too difficult and eventually abandon it.
In the end, once you better understand the user journey, you'll have a complete picture of what kind of content your user needs at each step of their journey to help them decide. Putting the user's needs first results in quality documentation and builds trust.
References
Winters, S. (05 December 2019). What is Content Design? Content Design London.
Found on Twitter. Content precedes design quote.