Why aren't help docs better?
"Everything Starts Out Looking Like a Toy" #104
Hi, I’m Greg 👋! I’ve written 100+ essays on product, data, and process for an idea or future product direction, often data between systems. What’s a key topic? System “handshakes”, the expectations for workflow, and the jobs we expect data to do.
Read more: What is Data Operations?
This week’s toy: a chrome plugin that uses computer vision to find and replace text within images. The meme possibilities of this are endless, even if that probably isn’t the intended usage. Edition 104 of this newsletter is here - it’s August 1, 2022.
The Big Idea
A short long-form essay about data things
⚙️ Why aren’t help docs better?
Perhaps this is your mental image of the perfect in-context help within a product. When you virtually walk into the product for the first time, a helpful librarian welcomes you to the library and shows you around. “Here are the most important things you need to know”, and “here is some information you can read to learn more” are the things you hear. They leave you with a magical communicator you can use to contact a helpful person at any point in your product journey. You feel calm, open, and ready to learn.
More often, your initial journey might feel like this meme: surprising and kind of painful.
Before you know your way around, you might not know how to use the product. Even if you know where to click to make things happen, it might be hard to understand the impact of what you’re doing. And you are likely to encounter some new words and terms that are not familiar. Enter the Help Doc.
Why help documentation?
Help documentation is a standard form of answering frequently asked questions, orienting a new user to features and functionality, and generally explaining what to do. Companies that provide “help docs as a service”, like Zendesk, Helpdocs.io, Helpscout, and products that enable content management as a service, like Contentful, provide content management for the help content you might want to see in a product.
Yet it’s too often arranged in Topics - broad areas or buckets for content – and Articles - the individual posts that present knowledge to the user.
We use full-text search as the bridge to help authors and readers when the exact content is not that easy to find. But the underlying problem is rooted in the information architecture of this help content and is the reason that most help sections feel disconnected from the products they are supporting.
User stories are typically broad
As a new user, you have different needs than an experienced user.
As an infrequent and experienced user, you may need reminding of key concepts.
As an experienced user, you may start to use the product in very different ways than it was originally intended.
These are broad needs, and the concept of a topic-based information taxonomy stumbles to meet them.
We need to build a grammar of learning and practice into our help systems to introduce concepts to users, help them understand how to place these concepts into use cases, and to encourage them to learn how to move beyond the initial product need into the “art of the possible” by setting up a grammar of usage to help them incorporate what they are doing into the world that they know outside of the product.
Building a concept map
To unlock the potential in documentation and to build a more flexible structure for educating many different types of users and simultaneously lowering the burden on documentation professionals in building this knowledge content, I believe we need to change the basic model of the topic-based help center and move to an attribute-based model of documentation.
When a new user encounters an automation feature for the first time and doesn’t know the concept of a sync or a destination, or how to map source fields to a data model, or the very basic idea of how often that automation will run (on demand, once an hour, once a week? It depends), they need different help than another user.
Combining the attribute (user tenure = low) with the area of the application (/automations) and the concepts needed to understand the action (a glossary, a definition for a basic automation or sync, and the location of key configuration information in the UI) might give a very different “just in time” list of help content. Add to this the ability to track which content the user has seen before or has marked “I’ve got this - I don’t need to see it again” and you are starting to build a model that will make the help content someone sees much more usable.
Making Just-in-time help possible
Ok, so this won’t happen automatically. But the basic tenets of this information architecture are easier to assemble than you think. Combine the “tags” available in most article and topic-based systems with an information taxonomy that is more expansive than articles and topics. Then you can compare the information in your user records with the search parameters that best match that user, the page or application area where they are doing a thing, and the experience level of the user.
Here are some content buckets you might consider:
Concepts are broad descriptions of the core items in the software (terms and definitions are familiar content items here), but go beyond a simple glossary. When describing concepts, you are explaining how the atomic pieces of a system build on each other to make something bigger and better. To understand a spreadsheet, you must understand the idea of a file stored with data in an array format. But to do this, you are introduced to the concepts of “rows”, “cells”, and “formulas”, which are all ways to manipulate the base data in the spreadsheet.
User Personas are simply descriptions of the type of people who use your software. Often this might bucket into experience levels (brand new, intermediate, advanced) or describe a type of user having a specific use case, like a marketing user who needs to upload a CSV file of marketing leads from a webinar event to deliver fresh event leads to Marketo or Salesforce. User personas start to describe the user, their motivations, and why they arrived here to use the software (or to find help).
Features are the specific places you go in the product to do individual tactical things related to the goals for the persona. For the marketing user needing to upload leads, where do they go to upload the file? What is the specific keyboard shortcut to copy some text and paste it elsewhere? Are these things available as global expectations or only within certain menus or actions?
Strategy is the way you are combining your tactics and using features to meet the specific needs of a persona while mastering your knowledge of the concepts of the product. The right strategy to load your leads after a webinar might be different for a first-time user or for an experienced user with a complex system, and they would use the same concepts to experience their goals.
A better help experience
Help should be viewed as a service, not just as content in topics and articles. This means making help content available in a flexible API is the first step toward delivering the right content to the right user at the right time.
A better help experience:
delivers content that makes sense for the task you’re doing
is optimized for your user level
is multi-modal and contains a combination of app overlays, videos, and readable content
Of course, it would help if a friendly librarian is also only a click away.
What’s the takeaway? Product documentation needs to evolve to better support the needs of users and the dynamic nature of products. To optimize the use of existing resources and make it easier for writers to turn out content, adding the use of content mapping to bring together personas, attributes, and product areas will increase the chance the documentation is useful for more people.
Links for Reading and Sharing
These are links that caught my 👀
1/ “Become a sustaining subscriber” - car manufacturers are increasingly testing options for making you pay them every month for features that you took for granted, including heated seat options. The reasoning for this seems clear: they are interested in building subscription revenue through software-like features and moving away from the initial purchase benefit they get when you purchase a car. This also adds potential revenue from used vehicles, which today don’t benefit the original manufacturer. Yet this idea of a subscription seems really weird with a physical good, unless the benefit you’re getting is so good that you can’t live without it (access to a wireless network as an extension to a pocket computer comes to mind). If GM could sell me faster commutes, this subscription would seem more interesting.
2/ AI for Charts - it turns out when you give Dall-E 2 prompts to create data visualizations, it can make some very interesting illustrations. I find these compelling not only because they are clever and beautiful, but also because I think they will drive better data retention and literacy among people who view data viz.
The biggest problem with charts and graphs, normally? They are boring. Dall-E’s graphs are anything but boring.
3/ Start by starting - this great short article on prototyping through demos is a fantastic example of how a simple process can yield outsized results. The next time someone comes to you with an intractable problem, start by starting … something. The act of demoing will help you to find things that don’t work and you might find what does work much faster. Demo more, and avoid “analysis paralysis.” You might have to get over the feeling of showing something that’s not quite ready for prime time.
What to do next
Hit reply if you’ve got links to share, data stories, or want to say hello.
Want more essays? Read on Data Operations or other writings at gregmeyer.com.
The next big thing always starts out being dismissed as a “toy.” - Chris Dixon