Anita Diamond - Cognitive Ergonomics in Technical Writing - Lessons from the Field

This is a summary of a talk given at Write the Docs Prague 2021.

Anita likes to make art out of ordinary household objects. She’s worked as a researcher, a journalist in telecoms, and as an IT trainer. She’s also really passionate about learning. What she loves about technical writing is it gives her a chance to fuse disciplines and interests, and foster adoption of products through knowledge and understanding. 

Most recently she’s been working in blockchain and crypto. It was like being plunged into a whole new world, but she works for a blockchain infrastructure company now.  

Naming and terminology

How do we know we’re talking about the same thing? It’s challenging to explain technologies in a way that is useful and comprehensible. 

She showed us a video that features a scientist talking about a very confusing piece of technology. We don’t understand what those words mean, and our brain learns new words by understanding the context around the new word. We try to link the new word with words we already know. 

It takes longer for the brain to decode low frequency words. Without linking to existing words, it’s hard to build a scaffolding or framework to support our understanding. We’re guilty of the curse of knowledge - being immersed in a particular subject creates a form of blindness that prevents us from communicating with people who are less familiar. 

Overcome these challenges in the following ways:

• Come up with categories to build a better mental representation

• Write the words down for another mode of perception, visually as well as orally

• Provide diagrams to illustrate the words

Naming and terminology in crypto and blockchain is notoriously difficult, with new terminology invented regularly. 

There is no consistency among different countries and regulatory authorities. A lawsuit is ongoing regarding the use of terminology in the field. 

Create a glossary and link to it when you refer to your new term. Link to more information if a user wants to find out more. 

Provide the least information required by a specific audience to perform a specific task, and provide this information in the right place at the right time. 

Fast and slow thinking

How can we support people to think deeply? Daniel Kahnemann describes two distinct modes of thinking: System 1 that is instant, unconscious, intuitive, and automatic, and System 2 is slower, conscious, rational, reasoning, deliberate thinking. We mostly use System 1 because it requires much less effort. 

For example, when signing up for a new account for an app requires System 1 thinking. 

Signing up for a crypto wallet is another example of system 1 thinking. You need to remember your master password in order to access your funds, so it would be better off to encourage people to use system 2 thinking. 

System 2 thinking is affected by retaining around 7 items at once. The crypto wallet requires 12 or 24 words in order to access it, so there’s no way to unconsciously sign up for a crypto wallet. You can’t copy and paste, or take a screenshot. The only way to record it is by writing it down. 

The previous example relates to some key points we should remember about documentation. Docs should be an information experience (IX) alongside UI designers. Focus on: 

• End-to-end user journeys

• Usability of information

• Design content to support cognitive ease

• Use multiple media to engage

Docs culture

How can we work with organizational culture and behavior to promote great docs? 

Developing a culture of sharing knowledge across disciplines is important, and cultivating an awareness of the whole docs lifecycle. This includes maintenance and curation of docs, and archiving outdated documentation. Measure the impact of documentation to ensure they’re getting read and users are finding them useful. Aim to have great internal documentation that is organized and up-to-date. 

People often have preconceptions about technical writing that don’t quite fit. We should align our approach with that organization’s culture and see where we can provide benefit or educate people. Define a docs process and educate workers about it and the value of good writing. Docs should not be an afterthought at the end of a sprint - be involved at the beginning of a project to ensure completeness and quality. 

Seek sponsorship from a leader or a senior person to promote the value of the docs. 

When there’s too much to document for one person, empower people with skills to contribute. Create doc systems that work with existing behaviors so that people can easily contribute and provide training. 

Instead of documenting without a clear purpose, request a user story with evidence such as a client request, user feedback or support ticket. 

Final remarks

Use these tips outlined in this talk to encourage slower thinking in your users. Avoid using overly technical terms unless absolutely necessary, and when you do try to link to a glossary. 

Finally, promote the value of docs within your organization by educating your colleagues and providing training. 

Listen to the full talk here.