Documentation Overload: Can Comprehensive Documentation Hinder Product Adoption?

I remember watching telenovelas as a kid and hearing in dramatic sequence, “The heart wants what it wants.” Over time, I’ve put that akin to “the brain wants what it wants” with an addendum, “…and will get it or leave”. I’ve applied this to every digital experience requiring human interaction, and software product documentation isn’t exempt. How do you give users what they want in your documentation, and conversely, how do you exclude what they don’t desire so ultimately, they don’t leave? This decision is more challenging when you’ve built a robust and complex product.

This post reflects on the above postulation from experience. Documentation bloat (as I like to call it) is inevitable as a product grows and matures. Advanced features are thrown in while technical writers struggle to build the ramp from gradual onboarding on shallow water to the eventual Mariana trench-like depths. In the depths, it’s tough to reconcile a user’s experience from the shallows as multiple paths, complexities, and goals now exist.

More isn’t always better. Can you say the same for product documentation? How do you fix this? Like every story, let’s start with who, what they want, and how they think when approaching your documentation.

Who did you write your documentation for?

Documentation, knowledge base, help center, developer portal, and resource section are multiple designations that ultimately say mostly one thing: “This is where you find information when you have a goal and need help.” In the context of this post, documentation denotes any of those.

Naturally, with software products, documentation is written for two kinds of users:

• Technical users: Software Engineers, Architects, Product Managers, and overall product team members. They’re primarily focused on feasibility assessments and technical implementation.
• Business users - These include go-to-market teams, business executives, web admins, and customer support, and are focused on day-to-day usage, general knowledge derivation, and business decision-making.

Understanding this clear distinction is the first step to correctly discerning the user’s journey once your documentation is visited. Similarly, the goals of these users differ, and your documentation should be explicitly structured along those lines.

Speaking of explicitly, a common mistake is assuming a type of user fits both personas and as such, the documentation is built with that user in mind. Albeit split into technical and business documentation, the line is blurred. Once the documentation grows, the problem becomes evident as this user category is uncommon, or rather, it’s inefficient to box most users into this category.

With a concrete understanding of who visits the documentation, the next step is to explore their objectives.

What do users come to your documentation for?

With a focus on mental overload, the time anticipated to be spent by each type of user is a common factor to consider. This largely depends on their objective, and speaking empathetically, each user’s journey should be put to the test on the following questions:

1. Are they studying the product?
2. Are they using the product?
3. Are they in active development with the product?
4. Are they looking for something definite, like a product/API reference?
5. Are they looking for general knowledge in the product space?

For example, when developers are in the arena, they seek code blocks, skim through large bodies of text, and often care about the neatly placed “copy button” at the top of each code block.

Each of those five questions poses a different mental model for the user, which influences their expectation of your documentation. The faster they can reach this goal, the better their experience. Again, the brain wants what it wants, or it’ll leave.

Structure plays a massive part in reducing this time to value for documentation systems. The team at Divio created a great resource on how documentation systems should be structured around user goals and objectives. It explains how documentation types can be oriented around one of the following:

1. Learning
2. Problems
3. Information
4. Understanding

You should take a look if you haven’t. For the scope of this post, we’ll leave it at that.

With a clear indicator of who comes to your documentation and their objective, how do you know if they’re overloaded? Let’s study some indicators.

Indications of documentation overload

At Hackmamba, the biggest mistake we’ve seen teams make is overlooking the inefficiencies of their documentation simply because internal users can quickly find whatever is in the docs. The power user bias - yep, I just coined that.

Since the documentation is a living document, not just in development, we recommend that its assessment be an ongoing, never-ending process. An effective way for internal teams to evaluate their documentation is to tell path-defining stories with their documentation. These stories should answer any of these three user journey questions specifically on a feature or product item. For a hypothetical fintech product, draw a specific path while answering these questions:

1. How will a user naturally find the refund customization options of the Node.js SDK?
2. What information will they come across along the way? How relevant is all that knowledge?
3. What specific piece of information do they want? An example code block or explanation of parameters?

Going through this natural flow to answer the questions for critical and prioritized features of your application furnishes a clear indication of your documentation’s simplicity.

Here are other methods to find out if your documentation is overloaded.

Evaluate the average engagement time

Assess the average engagement time for your documentation pages, bearing in mind the expected time to derive value from the document, both for a new and a power user. This information is found in analytics tools, and specific tools let you create paths with multiple touch-points and specify the average time to complete the path.

Infer from support requests

While certain bits of information may seem rightly placed and “easy to find,” support requests tell the truth about what information users have difficulty finding. I’ve used a product whose public support responses have proved more valuable than their documentation, even for simple product problems. Checking frequently asked questions in the community for a seemingly “easy to find” documented solution could clearly indicate overload.

Survey your users

No one likes surveys, but if you’ve built a dedicated community of users, you should send a survey to find out how efficient it is to find information in your documentation without getting lost or feeling overwhelmed. This applies to both technical and non-technical users.

Unmoderated user tests are also a great way to understand your documentation experience. Get on a call and ask a user to find something in the documentation without your help or interference. It could be general information about a paradigm or the implementation of a feature. Observe the critical and alternate paths they take to find the document.

Dogfood your documentation

Dog-fooding simply means using your product (in production). In this case, we recommend applying whatever internal documentation strategy to your external documentation to expose false assumptions. For instance, it’s ironic and awe-striking to see teams struggle with internal technical documentation but seemingly excel at external documentation even though both sets of documents rely on the same systems and processes.

Another way to dogfood your documentation is to use it for marketing/developer enablement efforts like livestreams, webinars, etc. You’ll be shocked at how horrendous your documentation is when your engineers try to use it on a live stream.

Track search queries

Search is critical to documentation systems, and tools like Algolia make search integration seamless. Search results are an often overlooked piece when considering documentation analytics. If you haven’t instrumented analytics on your search bar, do so and evaluate the frequently searched queries. Once found, it’s worth considering the path to the solution for overload.

Get fresh eyes on your documentation

My all-time favorite tip. Get a fresh perspective on your documentation. Typically, at Hackmamba, we recommend this with new hires on the product team. Have them complete specific actions, both simple and in-depth. The best case for this is in the evaluation of tutorials. Ask the user to reach the tutorial objective without following the tutorial documentation. Ask for feedback on their experience building from scratch, then take notes of portions where they lost it.

Now you know how to spot overload, how do you fix it?

How do you avoid or fix documentation overload?

Structure, structure, structure. We touched on structure earlier and why it contributes a great deal to fixing documentation overload. Here are other ways to mitigate it.

Apply empathy when writing documentation

The best documentation is written empathetically, not only as a manual for others to follow but also as a guide for oneself. Put yourself in the shoes of your reader each time. Role-play the user personas and make valid assumptions of their knowledge/experience level where necessary. Ask questions like, “Will someone new to our platform rather know how to do it this way or the other way based on their experience?”

Use visual cues

If a picture is worth a thousand words, how much is a video worth? Explore various modes of visual content to introduce a user to different concepts or drive home the point. YouTube video embeds are sufficient. However, tools like Loom make it seamless to record and share videos. Flow charts, user flow diagrams, and architecture diagrams also communicate concepts in fewer words while providing an anchor for future reference.

Answer “why” summarily and provide redirects

Every action on your documentation has a prevailing intent. The intent could be stated progressively or explicitly. Directness is highly recommended in this case, as certain users would skim through your documentation looking for a specific solution with a partly built-up problem frame. Clearly stating the intent before actions in the documentation alleviates the mental burden of reading through heaps of content before reaching a solution.

Provide fragments for code blocks

150+ lines of code in a code block? Ditch that. Break code blocks into chunks matching specific actions a user would take. Mention the action and state “why” before writing the code. This mainly applies to tutorial and guide sections.

Provide context in the code, but keep it succinct

While keeping the code fragmented is vital for quick perusal, providing context in each block is also important. When engineers develop, their use-case or setup may slightly differ from yours; it’s imperative to use comments in parts of the code block to specify what content should have gone where. Here’s an example of a context-rich javascript function block:

function random(){
    // Other variable declarations go here
     let randomNumber = Math.random()*10
    // Side effects and event triggers go here
}

This ensures the snippet above provides only the knowledge required to complete that specific action, and the reader doesn’t bother about other information.

Keep the main content updated and maintain a changelog

Your documentation, albeit a living document, serves as a source of truth for engineers and practitioners in active exploration through proof-of-concepts or product development. Hence, your documentation must remain updated and consistent at all times.

When significant or breaking changes are introduced to the product, mention them boldly on the affected page in the documentation with a hyperlink to the changelog. This ensures that users in active development don’t run into bottlenecks when developing over a more extended period within which your product has gone through multiple improvements and iterations. Effectively structuring and maintaining a changelog is as essential as supporting the primary documentation.

Split content correctly

A common mistake documentation managers and writers make is to pour all information on a page for each feature documentation. This is a quick way to overload a user. Long-form pages solicit psychological commitment from a user to peruse the page even though the task at hand can be completed with content in half the page.

A downside to this is users could spend time reading a full page in detail only to realize the page doesn’t contain the solution. This is a leading cause of integration abandonment and developer frustration. We recommend strategically splitting the page content into multiple pages that match medium-sized development goals while listing each page title on the side navigation bar for quick access.

Optimize search

As stated, search is an essential and “must-have” feature of all documentation sites. The more granular the index, the better. Explore using tools such as Algolia to add full-text search to your documentation. Recently, you can leverage AI to search your documentation in natural language, and multiple tools abound to help with this. Check out devdoc.ai if you’d like to add GPT-powered natural language search to your documentation.

In summary

If you’ve made it this far, you’re on your way to crafting seamless, streamlined, goal-oriented documentation for your users. We discussed documentation overload, its impact on users, and the adoption of your product. Writing better documentation isn’t rocket science. However, it takes careful and strategic intent to get it right.

Hackmamba has helped unicorns and startups drive deeper adoption and increase time to market with the right product documentation. Let’s discuss how we’ll augment your product team with highly-skilled technical writers, strategists, and editors to boost your developer experience and drive business value.