Documentarians in a self-service-first world

Writing documentation is your job today. What about next year, or three years from now? When large language models can generate infinite documents directly from the codebase, and your customers just ask their own LLM for answers, will there be work for purely meat-based documentarians?

Yes.

I suppose you’ll want more detail than that, though.

The future of online customer support is self-service first, specifically AI-mediated self-service. Because AI tools are built on a foundation of text, the creation, maintenance, and crafting of that text is critical to good service.

The role of documentarian will remain, but for people to add value in that role will mean closer ties with support teams, adopting some content design techniques, and writing for AI in addition to people.

So that’s the short version…now let’s get down to specifics.

The role of documentation

Documentation is an ongoing attempt to put reality on record. These things are true, this is how they work. A collection of facts, neatly organized and arranged. But that’s not all it is, is it? The marketing website can sell a story and create a picture in the mind of a consumer, but documentation has to connect that story to the mechanisms behind the purchase curtain.

When your customers read your documentation, they are adding structure and strength to a mental model of your company, and the products and services you offer. Any support veteran will tell you that plenty of support questions stem from fundamental misunderstandings where the customer's mental model of what the product is and how it works does not match reality. The language, format, hierarchy you choose for your knowledge base form a scaffold for people to build their understanding of all the different parts of your offerings and how they fit together.

Documentation can go beyond the “what” and help people understand the “why” of your features, products, and services. Why these features in this order? Why not this other product, or name? People reading documentation begin to understand the choices made, and that helps them better predict where to look for things and how they probably work.

Beyond directly answering questions, good documentation is building customer confidence, improving service experience, and reinforcing the company brand. Finally, as the source of answers for customers and for customer support teams, the language of documentation shapes the way your products and services are talked about. It’s a hard working part of the business.

Documentation does not exist in isolation, of course. It’s not stone tablets buried in the desert, it is living text modified over time and interpreted, explained, and applied by people. And the most critical of those people are the customer support teams.

Documentarians partnering with support teams

In the age of large language models, will there even be people on the support team? Absolutely. Perhaps not as many per team as there have been historically, but so much of good support is outside of the narrow window of “correct answers” that people will remain necessary.

The most effective documentation sources are responsive to changes not just in the products and services being documented, but in the customers using them, and the broader market. What made perfect sense to customers from 3 years ago might be confusing to people who found your website last week, because they come in with different backgrounds, levels of experience, and expectation.

For that reason, successful documentarians must build a feedback loop that encompasses customers, customer support, and knowledge base writers (plus the various tools each employs).

AI-mediated self-service experiences begin the loop. Customers who find their issues unresolved filter into the human-powered support experiences where the support team can assist them, but are also able to identify any gaps or limitations in the self-service system.

Customer support can collect those gaps, gather additional context from the customer, and pass them on to the documentation team to be addressed. Technical writers can work closely with support to fully understand the needs. Improvements made to the documents themselves, or to the retrieval systems used to access them, are then accessible to customers, completing the loop.

I’ve written about this support and technical partner relationship in more detail too (or you can watch my Write The Docs talk ). Collecting customer insights is the start of the job; writing and designing the amended documentation is the rest.

4 content design techniques for modern technical writing

For many years, we’ve considered search engines as an audience for documentation, particularly as the engines continue to extract content from websites to display directly on search results pages.

The newest audience for your documents is artificial intelligence bots, which imbibe support documentation along with everything else as grist for their conversational mills. The particular way in which AI tools retrieve and make use of documentation will affect how we design pages. Here are 4 approaches to consider.

1 - Design for modularity

Retrieval-Augmented Generation (RAG) is an AI framework used so that AI tools will search your knowledge base and other data sources for the most relevant information before it tries to generate an answer.

AI retrieval is all based on grabbing chunks of text at a time. You write your documents to be a beautifully plated meal, but AI retrieval treats it more like a fondue, turning it all into chunks then poking at it with one of those special forks. You want each forkful to contain just one delicious concept, so the AI has a better chance of mapping the right information to your customer’s request. 

So rather than mixing two different ideas up in one paragraph, keep them separate. Nobody wants someone else’s bread turning up on their fork.

2 - Write task-oriented documents

Customer prompts tend to be written in terms of actions—the things they want to get or do. “How do I cancel my subscription?” or “change my address”. Rather than write documentation that centers your internal categorization of features, write answers to the intentions you can predict customers will have.

Your support team will be a great resource for identifying those most common tasks and the way customers tend to ask them, and writing to those tasks will help improve AI retrieval as well as human browsing.

3 - Use headings as retrieval signals

You’re probably already doing this for your human readers, but having clear, structured headings for the elements of your document can be used in contextual retrieval to give the AI a better chance of avoiding errors. So instead of using a general heading like “Subscription options”, get actionable like “Canceling your subscription on the account page”. Tell the AI (and people) exactly what the paragraph is about.

4 - Consider out-of-context readers

When writing your documentation, you can’t assume that all readers will be reading the page from top to bottom. Even the people who arrive on the page itself might be scanning for the most relevant section, but increasingly your readers will not see the page itself at all. They’ll get an interpretation of the text in a chat window, or a results page, outside of the knowledge base context.

So try to write each chunk as self-contained as you can, little helpful modules of content that can build on each other, but don’t rely on being together.

The documentarians of tomorrow

Chances are that you’re already doing many of these things. You’re reading KnowledgeOwl's blog (unless this is now a chunk retrieved by an AI tool), so you’re well informed. But it’s worth acknowledging that the stakes are much higher for poor documentation today.

In the past your support team could be a buffer absorbing incomplete or stale knowledge base documentation. They know when not to rely on a document that has fallen behind. AI tools do not, and even worse, you may not always know when they are repeating inaccurate information.

A customer who has been served a very confident, but wrong, answer by an AI tool isn’t likely to question it. Support teams may never hear from them.

Your job is now to serve customers, support teams, search engines, and also AI tools. You must be the authoritative source of truth for all of them. In the same way that you learned how to structure, write, and format a document for human customers, it is now time to learn at least a little about how to do the same for AI tools.

You don’t need to be an AI expert, but you should know enough to avoid devaluing your own documentation.

The document is the keystone

The future of customer support is not “AI first”, it’s self-service first. The AI is just another tool in the chain that joins customers to the information that helps them move closer to their actual goal.

Whether through direct chat, independent AI agent queries, or a good old fashioned knowledge base browsing session, great documentation is the keystone of support. If it fails, the rest of the support experience will soon fall apart.

Documentation represents hard truth that can be relied on by every consumer of it, whether customer, support rep or AI agent. 

There’s plenty of work to be done.