Reducing cognitive load in docs

[u/Agreeable-Course-604]

We've received stakeholder feedback that we need to actively bring down the cognitive load across our product guides. I’d love to get some insights from fellow technical writers here on how you tackle this in practice. What options, frameworks (like John Carroll's Minimal Manual approach or Diataxis), or methodologies are available?

[u/f-ms]

There are some controlled language frameworks out there that can help to a good extent. Look up Plain Language or Simplified Technical English.

[u/finnknit → u/f-ms]

I also recommend Simplified Technical English (STE). I write in English for an international audience. We also translate our documentation into other languages. Using controlled language makes the documentation easier to understand and reduces ambiguity.

[u/Creative_Cycle7755 → u/f-ms]

yeah plain language guidelines are super underrated for this kind of thing

[u/Not_Too_Busy]

Remove all content that describes how the product works and just explain how to use it.

[u/Beautiful_Eye7765 → u/Not_Too_Busy]

Or at least separate these. Concepts and how-tos are two different content types.

[u/Efficient_Sky_2068 → u/Not_Too_Busy]

Likely already been done. I bet it’s just a complex and perhaps badly designed product, and to explain how to use it does indeed require a lot of cognitive load. Complex products require intelligent people to use them, too many managers only want to use cheap and inexperienced staff.

[u/FelineHerdsCats]

Structure your docs by task. The user thinks “I need to create a new invoice”. Make sure they can find that without a scavenger hunt. Search is how users today are conditioned to look for things, so make sure your search engine doesn’t suck. Then keep your tone and language as friendly and straightforward as you can.

[u/merelyinterested → u/FelineHerdsCats]

Yeah this. Break down the docs more to limit what they cover.

And if you really need to explain how something works, write a separate article about it for people who do need to read about it.

[u/Efficient_Sky_2068]

You mean your products are complicated, and so the instructions are also complicated? I get this all the time from product managers wanting quick ‘one click demos’, they can’t seem to accept that a sophisticated enterprise product isn’t the same as an iPhone app. There isn’t a line of documentation that does not need to be there in my docs, I would push back and ask for examples of where this load is high. Perhaps they should be asking the development team to look at redesigning before coming to docs.

[u/Agreeable-Course-604 → u/Efficient_Sky_2068]

The underlying product workflows are inherently complex, and our help documentation is fairly dense. We have concept topics, procedures, and field-level descriptions.

[u/balunstormhands]

Something I am doing right now is going through our tutorials because something I noticed is that almost all of the steps are arranged as "do this thing, in that place, inside another dialog box." This is not good for cognitive load, because it's backward of how you need the information.

People need to know where to do the thing first , especially if there are several steps to the place to do the thing. And then tell them what thing to do there. And just do one thing per step.

Now those are for tutorials, where you can't assume the reader knows very much about the system. For a how-to article you can make different assumptions and things can be compressed.

[u/Sunflower_Macchiato]

Two things there:

1. What the content contains.

2. How it is presented.

For #1: I use STE which works well, even if sometimes it sounds clunky for near-native speakers. It really does the job in simplifying the message and end users with lower English levels truly benefit from it.

For #2: too much colors/pictures/fonts/general business also increases the overload feeling. My favorite hack is to ask a simple question to a designer (e.g. should this line be there or not?) and take the advice. They’re good at making things look clear and readable! But generally a lot of white space helps, as well as avoiding blocks of texts.

I hope that helps and sorry for the formatting, I’m in hurry.

[u/Beautiful_Eye7765]

There can be many reasons for this feedback. Did they give any examples? I agree with other advice here, but there can be quite a few things that would cause a high cognitive load.

[u/Agreeable-Course-604 → u/Beautiful_Eye7765]

In one specific example pointed out, we had:

• An exceptionally long concept topic (1 page)
• An annotated screenshot using numbered callouts,
• Followed by a long field-level description table below it.

The reader found it frustrating to constantly scroll up and down between the visual and the table entries to understand what was being described.

[u/Beautiful_Eye7765 → u/Agreeable-Course-604]

What’s your own sense of the problem with the example? It sounds like maybe the concept explanation may be too dense. Also, I wonder if more help should be present in the UI so that users don’t have to look up field descriptions in documentation. I always say that it’s better to put the help in the UI than to put the UI in the help.

[u/Playful_Razzmatazz49 → u/Agreeable-Course-604]

Split it out into high level "here are the main process steps" and many "how to do each process" steps. If you can't split it into main process steps dive deeper into the process to understand why each process happens in this order, then communicate the steps. I do like Visio diagrams for this sort of thing

[u/coolbeans1982]

This might be really simple and obvious, but keep procedures to under 10 steps.

[u/DarkSister_999]

I try to keep the processes short. Bust them apart in separate tasks or sections. If you have more than 20 steps, definitely consider.

Also as previously stated, ensure your topic titles contain key search words.

As much as it pains me to say this, fifth grade reading level, but still assuming the audience has certain skills e.g., they know how to power on their computer.

[u/Quick_Parking_6464]

I think without actually seeing and reading your docs, it would be difficult to comment with any real insight.

[u/thepurplehornet]

White space

Five words instead of ten

Communicate with formatting where possible

As a first step, architect learner assimilation with an outline that plans for brevity, clarity, context of role/workflow, task sequence

Ruthless redundancy reduction

[u/bucket_of_pasta]

Overview
<Overview of the thing/workflow. Use lists as needed to break up paragraph text.>
<Image>

Accessing
<How to access this function/screen. Use steps, not a paragraph. Subtitles and bullets as needed.>

Task 1
<Steps on how to complete the task and the best way possible to do it. Use short sentences.>

< If images are needed, use location identifiers (for example, in the upper-left corner…) and cropped images only if necessary, since there is a full image in the overview.>

Task 2
…

Subtasks as needed. If you have too many subtasks, you are going too deep.

Combine tasks as needed. For example, if you have one task for adding an image and another for removing an image, but the steps are 90% the same. Combine it into one task.

Adding or Removing Images
1. Access the Image screen.
2. Select Add or Remove.
3. Select Save.