Learn these psychological techniques to take your documentation up a notch

Author's note: Thanks to support sorceress and cheesemonger Kate Mueller for her substantial contribution to this post.

Marketers are well-versed in using the principles of psychology to increase business value. They use psychological techniques like the science of scarcity to persuade prospective customers to click on links, sign up for trials and convert to paying customers.

Technical writers can learn a lot from the field of psychology to make sure that users can make the most of their documentation. They can do this by focusing on the end goal – enabling users to solve whatever problem they were having with the product.

The more complex your product and the more heavily involved users are with your service, the more important these principles become. You're actively working with your users rather than unintentionally working against them.  

We’ve come up with a list of psychological principles to keep in mind when producing your documentation.

See previous post: Psychological principles for knowledge base Information Architecture

Situational awareness

The first of these principles is situational awareness. Humans are hard-wired to scan for the wider context in any given situation. Questions go through their mind like: what is normal? What is out of the ordinary? What is the appropriate reaction to this situation? 

Then, what is likely to happen in the future based on this context?

In our documentation, we can provide the appropriate cues to clarify our user’s situational awareness. For example, situational awareness can be improved by clearly labelling your knowledge base, and also titling each article appropriately. You can also use interlinking to other articles and navigational elements to help users establish context.

It's tricky because we often don't know where our users will be coming from when they arrive at our knowledge base. Novice users are much more likely to lack situational awareness than experienced users – but all users can benefit from better contextual cues to help them make more of your documentation.

We can offer an example. One of the patterns we're adopting in KnowledgeOwl documentation is to address the fact directly that our users always have a variety of technical abilities and knowledge about KnowledgeOwl. 

Much of our documentation's historical focus has been on providing our users with how-to steps that get them up and running quickly and efficiently. This could be something like "here's how to set up x to do y". One of the changes we're making to this pattern to try to reach more user ability levels is to structure articles with a general layout. For situational awareness, we're trying to begin all articles with 1-2 sentences providing more of a description than just the title:

KnowledgeOwl example of docs

This helps orient users right away so they don't have to wade through unnecessary text. More experienced or knowledgeable users can just read the introduction without needing a step-by-step solution. 

Cognitive Load Theory

Cognitive Load Theory was advanced by John Sweller based on information processing research. Human short term memory can only contain a limited number of elements. This is why you shouldn't overload your users with too much information at once. 

The human mind forms schemas (theories) in the long-term memory. Schemas are employed during learning to reduce cognitive load, to make the learning experience easier. It's one of the factors that distinguishes an expert in a field from a novice.

Once a novice learns a new schema, more of their working memory can be freed up for the task at hand. This allows someone to gain prowess in the given area. It’s important to identify whether your users are novice, intermediate, or expert, so you can pitch your documentation accordingly. 

For example, including a case study at the bottom of an article providing the larger context for the information can be a good way to help your users build mental models. 

KnowledgeOwl providing a case study

Cognitive Load Theory is also a good argument to support the idea that we need to break our content up into chunks using things like subtitles and bullet pointed lists. 

The Law of Pragnanz

Also known as the Law of Simplicity, the Law of Pragnanz follows Gestalt principles by acknowledging that people have a need to see the whole picture. We simplify complexity by mentally merging separate elements into a unified whole.

"People will perceive and interpret ambiguous or complex images as the simplest form possible, because it is the interpretation that requires the least cognitive effort of us." – UX Matters

This principle can be applied to images but also relates to linguistic information. We like the interpretation that takes the least effort to arrive at. And Reification is when our mind fills in the gaps to complete the picture – often leading to mistaken assumptions. 

Keep this in mind when writing your documentation. Incomplete information means users will start to make assumptions about how something works, which are very likely to be wrong. 

Keep your documentation short and to the point. Don't use ambiguous language or try to make your documentation "interesting". Here's a great example from Box: 

Box example of simple docs

The clear, simple language directly communicates the information to customers in a bullet pointed list without adding any unnecessary details. Users can find what they need without having to fill in any blanks. 

The anchoring effect

The anchoring effect is known as "A cognitive bias that describes the common human tendency to rely too heavily on the first piece of information offered (the "anchor") when making decisions," according to Harvard Law School. 

This means that in any given situation, you will be biased by the first piece of information you see. You go on to use this anchor as a reference point when making later decisions. Keep in mind that your single page of documentation could be the first point of contact a user is having with your help content or even your product. 

Your anchor determines the tone of your article and provides some useful context. The information you present at the beginning (i.e. the title) strongly influences how they interpret the rest of the information. Spotify uses article titles that are direct and to the point: 

Spotify example of anchoring title

These short, action-oriented titles will stick better in your user's mind as they move through the article. 

Don't assume that users know what you know. Think about situational awareness, and provide as much contextual information as possible. This means users won't rely too heavily on the anchoring effect to make sense of your documentation.

Pleasure-pain principle

Sigmund Freud’s pleasure-pain principle postulates that humans are motivated to seek pleasure and avoid pain. The human mind tends to seek instant gratification. It's the part of your user’s psyche that rebels against unfairness – the unfairness of what they might see as the inconvenience of sometimes having to use documentation in the first place.

Very few folks read documentation to just learn how a thing works, or for fun. Most people only look for documentation when they are battling pain. This is when something isn’t working properly or they are already frustrated. Ameliorate the "unfairness" of users having to use docs in the first place. Make your documentation a source of pleasure if possible – rather than pain. 

It's a helpful reader context to keep in mind for all documentation: that people are already coming frustrated and the more pleasurable you can make your documentation experience, the happier they’ll walk away. It's important to invest in writing your docs in the most simple and pleasing way as possible, to offset some of the pain they're experiencing. 

The more pleasurable you can make your documentation experience, the happier they’ll walk away. Take inspiration from Help Scout: 

Help Scout example of pleasurable documentation

At KnowledgeOwl, after our 1-2 sentences for situational awareness, we also break things down into straightforward, discrete steps on how to complete a task or action. We want to get to these steps quickly and make them easily accessible for our power users, and those who don't need additional context. This also applies to the next point about the paradox of sense-making. 

Paradox of sense-making

The paradox of sense making was first defined by John Carroll, Professor of Information Sciences and Technology at Penn State who also coined the term "minimalism".¹

His work examining the learning process founded the field of minimalism in documentation. He discovered that less really is more when it comes to documentation, especially for new users.

As Carroll says: "[people] are too busy learning to make much use of the instructions. This is the paradox of sense-making.” Users don’t have time to wade through the perfect set of documentation. Your aim should be to solve their problem – immediately.

It means you need to get to the point in your documentation, fast! Slack gets out of the user's way with documentation that is both minimal and pleasant to use: 

This relates back to Cognitive Load theory and not overburdening your user with too much information. Providing context for situational awareness to how you structure your article also gets them up and running quickly. 

Information scent

According to Nielsen Norman Group, "Information scent refers to the extent to which users can predict what they will find if they pursue a certain path through a website." As soon as they hit your article, your users need to understand whether or not they are in the right place. 

Information scent is related to Information Foraging theory, which likens people seeking information to animals foraging for food. People will keep going as long as they keep finding clues that they are approaching their goal. As soon as the trail dries up, users give up searching for the information.

Provide obvious clues to aid your users' situational awareness in individual articles. This can include links to other articles within the body, or at the end of the article. Folks can easily navigate to other related topics in case this content wasn’t exactly what they needed to find.

Atlassian has invested heavily in their docs to signpost their users: 

Atlassian information scent example

In their article, Atlassian immediately tells the user who the information is for and exactly what the article is about. They even provide information about how long it takes to read the article, giving users control over whether they want to invest their time in this task. 

And even better, overall they have beautiful docs. 

Visual salience

Visual salience is the psychological mechanism that enables us to "rapidly detect potential prey, predators, or mates in a cluttered visual world."

The nature of perception means that some objects stand out from the background and from other objects. For example, a flashing red sign has strong visual salience. It's one of the reasons why we can only process a small area or a few objects at a time – not everything can have significance.

You can use this principle in your documentation to direct your user's attention to important information. For example, including a warning call-out to highlight information you want your users to notice above all else, or highlighting certain words in bold. It goes without saying that titles and subtitles should be properly formatted to call attention to them.  

Even when using call-outs, though, you can opt for more subtle formats for certain types of call-outs, as Spotify does: 

Spotify visual salience example

Avoid overwhelm by reducing the number of visually salient elements competing for your users' attention. 

Pattern recognition

Human beings are primed to seek patterns in our experiences, which we later use for pattern recognition. 

Pattern recognition is what helps us to understand language, to recognize the faces of people we know, and to appreciate music. Pattern recognition is fundamental to being consciously human.

We store patterns in our long-term memory and then match them with current stimuli. Learning patterns help us to predict what might happen in the future, and use mental shortcuts to help us make better decisions.

In your documentation, try to use meaningful patterns when arranging the information to help the user learn your mental models more quickly. Avoid creating patterns that have no meaning, as this will increase cognitive load and throw off the information scent. This includes patterns that are important to your internal staff or higher ups, but have no meaning for your users. 

One thing you can do is use documentation templates when creating individual articles. This keeps articles consistent in how things are laid out and where folks will find things, making pattern recognition faster and easier. You can have different templates for different types of documentation; for example, for tutorials vs. reference guides. 

Here's one of our examples: 

KnowledgeOwl template example

Your template should be unique to your organization and the style of documentation you need to produce. 

Even if you aren't using templates, having a style guide that your content writers can reference to keep articles structured consistently can also aid with pattern recognition.

Over to you!

As you’ve probably noticed, many of these psychological principles and techniques overlap with each other. Once you start digging down into the rabbit hole, you'll find unlimited ways you can try to provide better documentation for your product or service. 

Try to apply as many principles as you can in your documentation to help your users reach their end goal: solving whatever problem they have with your product.

Our very own knowledge base software KnowledgeOwl can help you create delightful documentation for your users. Take it for a free spin now. 

References

¹ The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill (1990) By John M. Carroll