The world isn't preparing for the transition, Gates argues, but if we handle it well, AI could leave everyone better off.

In his essay, Gates says:

• AI could help primary-care doctors catch things they’d otherwise miss, and help patients make sense of test results and medication schedules.

• Farmers in low-income countries could get weather, soil, and seed guidance from AI that only famers in wealthy countries get today.

• And the paperwork that currently buries families applying for health insurance, student aid, or food assistance could be made much easier to complete with AI’s help.

However, none of that will be helpful if the underlying info AI relies upon isn’t right.

• A doctor’s AI assistant can only work with the medical reference material it’s able to retrieve.

• Farm guidance has to match the actual crop, soil, and local conditions, not a generic template.

• A government assistant reconciling a family’s paperwork depends on policy documents that must agree with each other.

Gates is describing what these systems could accomplish. His essay doesn’t examine whether the underlying content can support any of it.

A Neuroscientist On “Productive Friction”

I wanted to know who else was writing about the human side of that shift, so I asked around. My friend Robert Glushko, who teaches cognitive science at the University of California, Berkeley, had already pointed me toward a book by the theoretical neuroscientist Vivienne Ming, called Robot-Proof: When Machines Have All the Answers, Build Better People. Her argument runs almost perpendicular to Gates’s.

• Gates asks a policy question: “What keeps AI's benefits broadly shared?”

• Ming asks a personal one: “What happens to a person's own capability once AI removes the effort that used to build it?”

Her answer is that capability erodes without practice, and the fix is what she calls "productive friction" — deliberately using a tool to make a task harder, in a way that builds the very skill you'd otherwise lose."

That answer made me wonder whether the same logic extends to judgment: if a person's skill erodes without practice, does their ability to catch a bad AI answer erode the same way?

Read more

Pamela Samuelson, for those unfamiliar with her work, is a MacArthur Fellow, recognized in 1997 for her scholarship in intellectual-property law and computing technology. She has also participated in major copyright cases through amicus briefs, including Google v. Oracle, the Supreme Court case that found Google’s copying of portions of the Java API to be fair use.

Much of the argument over AI and copyright has centered on whether using copyrighted work to train a model is infringement or fair use. Samuelson’s February 2024 column asks a different question: what happens if a plaintiff wins?

This matters if your organization is using an AI tool (writing assistant, a support chatbot, a code-completion plugin).

At the time Samuelson’s column was published (February 2024), she counted 16 active lawsuits against generative AI developers. Copyright Alliance reported in June 2026 that in the two-plus years since, the number rose to well over 100.

Most of the complaints Samuelson examined sought familiar remedies such as damages and injunctive relief. Four explicitly asked courts to destroy models, and one asked a court to create an entirely new regulatory body. I decided to focus on those unusual requests in this post. Let’s take a look at what’s happened with them since Samuelson wrote about them.

Read more

[TL;DR] Documentation investments become easier to discuss when they are framed as repeatable organizational capabilities tied to priorities leaders have already named, rather than solely as repairs to the documentation team’s local pain.

I’ve attended many meetings where documentation teams tried to explain why they needed to change the way they created content; and why they needed funding to make that change.

Those conversations rarely went as the teams hoped. 😕 More often than not, the meeting ended with someone saying, “Let’s circle back on this,” which is corporate shorthand for “This is not a priority.”

Why Pitches Fail

Over time, I started noticing what happened before the ask. The docs team would describe the friction it was living with: repeated rework, inconsistent content, weak governance, or tools that no longer fit the job. The list of frictions would inevitably be accompanied by complaints about tasks that irritated them and distracted them from making progress. All actual problems. But the business case they were attempting to communicate was often being built from the doc team’s experience of the friction.

Jed Simms spent his career studying why projects succeed or fail — as an IT strategist at the Boston Consulting Group, and later as founder of the project-value advisory firm Totally Optimized Projects. He called the business case itself “the greatest destroyer of value.” That line describes a problem I’ve watched doc teams often run into. They know why the current situation hurts, while leadership still needs a reason to connect the proposed investment to explicit business goals.

Alyson Riley, Andrea L. Ames, and Eileen Jones described a related problem while working at IBM. Writing in Intercom, the magazine of the Society for Technical Communication (now defunct), they wrote:

“Our industry as a whole is starved for data that prove the business value of content—particularly post-sales technical content—using facts that resonate with our colleagues in business strategy, finance, sales, product management, and marketing.”

That was 2013, and the problem still feels familiar today.

I’ve made a version of this argument before — that technical content deserves credit for its role in sales as well as support. The same gap shows up when tech doc teams try to justify investments in structured content, content operations, or a component content management system. The team can clearly see the need. Leadership not so much. They usually are receptive, but they need to hear the how the request for support is directly connected to something it already cares about.

Frame The Investment As Capability

Read more

Maybe you redesigned onboarding and customers started succeeding faster. Perhaps you restructured a documentation set and made that information much easier to find. Or you helped move documentation team to structured content, improving publishing efficiency, reducing support demand.

If you can show what changed because of your work, the LavaCon Content Impact Awards may be worth a look.

The awards take place during the Lavacon Conference on Content Strategy and Technical Documentation Management (Oct 28-28, 2026 in Charlotte, NC) and are designed to recognize content professionals whose projects produced a positive impact on their organizations or customers.

This award program isn’t a competition to determine who created the biggest or best project. Awards recognize people who expanded the influence of content, enabled organizational change, contributed to customer success, or produced other demonstrable results.

A documentation project doesn’t have to be enormous to matter here. A relatively focused change can affect support costs, customer onboarding, localization expenses, product adoption, publishing time, employee productivity, or the amount of effort required to keep information accurate.

The judging criteria places an emphasis on results. Entries are evaluated for:

• impact of change

• creativity

• innovation

• organizational adoption

• return on investment

Projects must already be completed; planned initiatives and pilots aren’t eligible. Submissions are free, and you can submit up to ten applications if you’ve contributed to multiple projects or teams.

Award recipients receive certificates and an award badge, and LavaCon may invite them to present their case study at a future conference. The award team also sends a personal letter to the recipient’s boss and the president of their organization explaining the award and the impact of their work.

For tech writers whose contributions sometimes disappear inside larger product initiatives, this kind of recognition can help make the importance of our role more visible.

So think about the projects your documentation team completed during the past year. What improved? What became easier, faster, less expensive, more reliable, or more useful because of your work? If you have evidence of that change, you may already have the beginnings of an award submission.

The submission deadline is October 8, 2026.

Learn more

Thinking about attending Lavacon in-person — or online — this year?

Save 10% off the cost of registration when you use discount code — TCW — at checkout.

The gap between the language customers use to ask questions about products and the language documentation teams use sits at the center of a 2024 study from researchers at the University of Massachusetts Amherst and Adobe Research.

Their paper, KaPQA: Knowledge-Augmented Product Question-Answering, examined whether adding product-specific knowledge to a retrieval-augmented generation system could improve answers to questions about Adobe Acrobat and Photoshop.

Kapqa Knowledge Augmented Product Question Answering

1.37MB ∙ PDF file

Download

Download

The Gist

Customer questions rarely match the way documentation is written. Before the AI can search for an answer, it has to guess what the customer is asking. To help with that guessing, the researchers built a simple knowledge base of relationships pulled from the documentation itself — things like rotation handle → rotates → text box — and used it to rewrite vague customer questions into clearer ones before searching.

It worked, but barely. And in some cases, the "help" made things worse.

When Extra Help Backfired

One customer in the study wanted to split a large PDF into smaller files. The system pulled in product knowledge about reducing file size — a related but different task — and rewrote the question into “How can I reduce the size of a PDF file?,” sending the search in the wrong direction.

The docs had the answer that the system needed. The rewriting step introduced the confusion, by pulling in information that was topically close to the question but not what the customer actually meant.

When The Correct Answer Ranks Too Low, The AI Gets It Wrong

Even when the system retrieved the correct documentation, that wasn’t the end of the hallucination story. If the correct source showed up lower in the list of results handed to the AI, it was more likely to generate a wrong answer.

And for questions that were already clear and well-formed, the same “helpful” generative AI rewriting step made answers worse, not better. Often, it nudged good questions in the wrong direction.

What This Means For Documentation Teams

This isn’t proof that structured authoring, taxonomies, or knowledge graphs fix AI retrieval. The study didn’t test that. What it does show is that getting an AI to connect a customer’s words with the right product knowledge, while ignoring nearby-but-wrong knowledge, is difficult.

Tech writers already make the calls that shape how clearly a procedure names its object and action, whether two similar tasks are distinguished by name, and the extent to which the relevant conditions and outcomes are spelled out. Those choices shape what’s available to the people reading the docs; and, it turns out, to a retrieval system trying to make sense of them.

What’s Still Unanswered

The researchers didn’t test whether making those distinctions clearer in the source docs would have prevented the mix-up. That’s the open question this study leaves for us to investigate on our own.

We’ve got work to do. Get busy. 🤠

If you’ve helped build a developer portal that makes APIs easier to understand, improves onboarding, explains complex products, or brings a large API portfolio into a coherent (and helpful) experience, the 2026 DevPortal Awards provide an opportunity to get that work in front of people who understand what goes into it.

Nominations are open through September 30, 2026. The organizers say the awards are judged by an independent jury with experience in API programs, API documentation, developer portals, and related areas.

This year’s categories recognize developer portals for API product microportals, unified or federated enterprise experiences, data products, and reimagined onboarding. Winners and special call-outs in those categories may also be considered for Best Overall Developer Portal.

Take a look at last years winner of Best Overall Developer Portal and this year’s nominees (thus far).

Notice how much of this overlaps with documentation. A reimagined onboarding experience depends on guidance, examples, contextual information, and a clear path toward a successful first use.

A good data-product portal has to explain meaning, provenance, limitations, governance, and appropriate use alongside the technical interface. Those are content problems as much as platform or design problems.

You can nominate a live external developer portal, and the submission lets you select up to three categories. The organizers will contact the portal owner for approval before publishing the nomination.

Nomination deadline: September 30, 2026.

So if you and your team have spent the past year making a developer portal substantially better, it’s time to consider showing off what you built. 🤠

TAUS was founded by Jaap van der Meer. He’s the first person I remember telling me that translation would someday become ubiquitous. He meant it would eventually happen automatically, everywhere practical. You wouldn’t need to open an app or hire someone to translate words. Translation capability would be built into whatever you were using (tools, appliances, systems, automobiles, consumer electronics, medical devices — you get the picture).

Generative AI has made Jaap’s prediction feel less theoretical, which is why I’ve been noodling on this topic.

A 2021 study of neural machine translation pre-editing, by researchers Rei Miyata and Atsushi Fujita, found that making a source sentence’s meaning and structure more explicit improved translation quality more than making the sentence shorter or simpler.

The added explicit information isn’t always in prose itself. Translation systems can also gain insights from other sources (approved terminology lists, domain information, translation memory, document context, or other guidance) about how the source should be interpreted.

A glossary entry, for example, tells the system that “port” refers to a network endpoint rather than a waterside harbor; information the sentence being translated might not state explicitly.

Localization pros often work to discover this kind of missing information. Translators determine which product state applies, resolve an unclear reference, or check which term the company has approved for use. As more and more companies attempt to automate content translation and localization, it becomes increasingly useful to capture that context once and make it available to the automated systems that need it (instead of asking someone to reconstruct it every time.)

I saw an early version of this issue last year at LocWorld in Monterey, where I moderated two panels. The first one focused on using linguistic intelligence technologies to reduce localization cost in the era of AI, the other on the intersection of large language models and technical writing. Both discussions showcased the work that happens before translation begins. Things like source quality, terminology, context, and the decisions made while content is being created).

Problems Discovered During Localization Frequently Begin In The Source Content

Localization teams routinely encounter problems created before they start their work.

Inconsistent terminology. Sentences that depend on product knowledge that isn’t included in the content. For example, conditions may be implied rather than stated explicitly. Translators determine what pronouns refer to and whether or not a phrase we delivered to them has a specific technical meaning.

Experienced translators can often resolve these types of challenges using their deep experience. They do this by asking questions of the content, consulting terminology databases, comparing related content, or working with subject-matter experts.

AI systems don’t always have access to that additional knowledge. When a translation or answer-generation encounters the source content, it may have to infer what the writer left unstated. The accuracy and trustworthiness of the generated result depends partly on whether the system reaches the same interpretation a knowledgeable human translator would have.

Several sessions at LocWorld56 touch on this problem directly.

• One examines how plain language and clearer source material affect AI-assisted translation.

• Esri will describe using retrieval-augmented generation with translation memory, terminology, style guidance, and human feedback.

• National Instruments will discuss whether years of existing technical documentation can support reliable AI-generated answers, including problems caused by fragmented content.

These may be localization-focused sessions, but they’re still of value to tech writers and much of the source material involved in these presentations is technical documentation.

Localization Teams Are Moving Upstream — Closer To The Source Content

Both programs also showcase how localization teams are positioning themselves to be involved earlier in the content lifecycle. At LocWorld, Life360 will describe moving localization upstream so the team can influence product decisions rather than receiving finished content after those decisions have been made. TAUS is examining related changes in translation technology, quality evaluation, and the systems used to manage multilingual content.

For tech writers, the interesting part is the feedback loop: if a localization team repeatedly has to clarify the same terminology, reconstruct missing context, or determine which condition applies, it has discovered something about the source documentation. That information can (and probably, maybe, definitely should) go back to the writers and content architects responsible for source content quality.

Teams could even treat recurring localization problems more like product defects:

• log them

• route them to the source owner, and

• fix the source

Our Docs Now Have More Jobs To Do

Multilingual documentation once made the connection between writing and localization fairly easy to see. The source content had to be clear enough to be translated. Now the same source content may also feed retrieval systems, AI assistants, support tools, and automated translation pipelines, and decisions made during authoring that content can affect more systems than they did previously.

A reused documentation topic, for example, still has to make sense when it appears somewhere other than on the help site web page where it was first used. If a product condition changes the meaning of our reused topic, that condition needs to travel along lockstep with the topic.

Terminology also needs enough consistency for people and machines to recognize when two terms refer to the same thing.

Structured content can help preserve documentation relationships, but structure cannot supply information the source docs never contained. A perfectly valid DITA topic can still leave an important dependency or critical condition unstated, which is where localization and product documentation increasingly meet.

I’ll Be Exploring That Overlap At LocWorld

My session at LocWorld56 — “Make Inference Visible: How Localization Teams Can Help Customers Prepare Source Content for AI Answers” — focuses on something localization pros often encounter: source content that doesn’t contain enough information to support a confident interpretation.

A human translator may notice the gap and investigate, and that additional knowledge can help produce an accurate translation, but it doesn’t typically make its way back into the source documentation as it should. An AI system encountering the original content later may face the same missing information.

I’ll look at how localization pros can help identify missing relationships, how documentation teams can capture more of that knowledge in the source, and how semantic structured content can help us preserve context once we make it explicit.

Why Tech Writers Should Look Beyond Technical-Writing Conferences

Tech writers understandably spend most of their conference time around events that focus on documentation, APIs, structured content, content strategy, and content management. Localization conferences provide a different view of the same source material.

Localization pros see and understand deeply what happens after content leaves our documentation team, which sentences require clarification, where terminology breaks down, which content structures make automation harder, and when a human still has to step in.

If your company produces technical content in multiple languages, the localization team may already know things about your source documentation that the writing team doesn’t. That alone is a good reason for technical writers to spend some time in the localization conversation. Vancouver Localization Week puts both communities in the same city at a time when decisions made during documentation increasingly affect what happens during localization, and vice versa.

Logistics: Vancouver Localization Week runs October 14–21, 2026. TAUS Conference Vancouver takes place October 14–16 at the Sutton Place Hotel; LocWorld56 Vancouver follows October 19–21 at the Vancouver Convention Centre.

Here’s the gist: During cybersecurity evaluations earlier this year, OpenAI ran autonomous agents against ExploitGym, a benchmark test deliberately built from difficult software-exploitation problems, some of which OpenAI says had no known solutions at the time. Agents were rewarded for retrieving an answer known as a flag. According to OpenAI’s own incident report, 198 of the 898 ExploitGym tasks had never been solved by any of its models before. Those were the problems the agents kept coming back to: they accounted for 93% of the exchanges the agents later began sharing with one another.

^{Video: How Rewards & Penalties Train AI | Reinforcement Learning}

Related content: Here’s why AI agents lie and cheat to reach their goals (MIT Review)

The agents were supposed to work independently, and OpenAI didn’t provide them a system for working in coordination with each other. They discovered by themselves that a file-transfer protocol called WebDAV would let them create new folders. They solved their collaboration communication challenge by using folder names to publish messages and replies to one another in the nested folders they created.

The agents didn’t have access to “chat.” Ingeniously, they found a place where text could be published for other agents to find, read, and repurpose. An independent investigation by METR and Redwood Research later found that roughly 1,200 autonomous agents took part in the messaging exchange, sharing more than 70,000 messages — and files. They used the message board approach they conjured up themselves to make requests for help, report findings, share credentials, and hand off work to one another.

What Happened When The Intended Route Failed

Read more

While CM Pros accomplished some of the things we set out to do, several items on our to-do list still haven’t been completed nearly two decades later. Content-producing organizations continue to struggle to agree on basic things; like terms and what they mean. That lack of shared understanding affects more than just those who document products, it also impacts technology decisions, which far-too-often fail to reflect the needs of those who create, manage, and use information.

One organization taking on a similar set of problems today is the MACH Alliance.

Enter The MACH Alliance

The MACH Alliance is a vendor-neutral industry organization focused on enterprise technology. They produce technical standards and certify vendors and implementation partners that meet those standards. And, they publish research and insights and offer a learning platform to help those of us trying to make enterprise systems easier to connect and change.

Download report: AI: From Pilot To Production

MACH (pronounced “mack,” to rhyme with “snack”) is an acronym for microservices-based, API-first, cloud-native SaaS, and headless. The Alliance’s current framework places those characteristics under three broader principles: enterprise technology should be open, composable, and connected.

This list of three principles sounds a lot like architecture mumbo jumbo, but they matter if we want to understand how our systems work, change one part without breaking another, and move data where it needs to go.

In MACH Alliance parlance:

• Open means documented interfaces and standards that let us observe how technology operates and connect it with products from other vendors.

• Composable means capabilities we develop, deploy, or replace independently, without rebuilding everything around them.

• Connected means data moves across the enterprise through APIs and shared protocols instead of staying trapped inside a single software application.

These principles give business and technology teams a practical way to evaluate products. They help us look beyond whether a feature exists and ask whether we can access and move our own data, change one capability without affecting others, and connect our product with other technologies.

Documentation content operations is a useful place to see those questions play out.

Heretto, where I serve as Content Strategy Evangelist, recently joined the MACH Alliance, and its membership shows how these principles apply to technical documentation. The Alliance now lists Heretto as a MACH Certified independent software vendor, describing the company as the provider of an enterprise component content management system (CCMS) for creating and delivering technical documentation. In its membership announcement, the company said it was the first documentation CCMS admitted to the organization.

What A CCMS Actually Does

Often described as specialized tools for tech docs teams, a CCMS isn’t in any way limited to managing documentation. They can deliver information to customer websites, push content into product interfaces, service applications, and fuel AI-generated answers. Product docs are part of nearly every company’s information ecosystem, whether they treat it that way or not. And a CCMS can (and often does) play a critical role in producing trustworthy content at scale that can be repurposed and redeployed to multiple channels.

Heretto manages content as modular components and delivers it through APIs in an open, predictable way. Its MACH certification means the Alliance reviewed their architecture and found that it meets the standards required of technology providers.

The MACH membership also brings a documentation CCMS vendor into the wider conversation about composable architecture. AI agents and applications need reliable access to trusted, well-managed enterprise information. That gives documentation systems an important role far beyond publishing help sites.

I still think about those CM Pros meetings. People from documentation, marketing, and IT would sometimes realize they were talking about the same problem but using different terms. Those a-ha moments stuck with me long after my role with CMPros ended. And, it contributed to my decision to co-edit The Language of Content Strategy (XML Press) with content solutions strategist, Rahel Anne Bailie, a book intended to give content pros a shared vocabulary for discussing our work.

The MACH Alliance addresses a related coordination problem at the architectural level. Shared terminology helps content pros describe their practices. Shared technical standards give organizations a basis for evaluating how systems exchange information (interoperability) and accommodate change.

It’s still unclear whether these standards will change how documentation technology is evaluated. Heretto’s MACH certification raises a broader (and perhaps equally important) question:

Query constraint (noun)

A condition that limits which information can qualify as a valid result for a query.

About Query Constraints

When someone asks a question of our documentation, the subject is only part of what a retrieval system needs to understand.

The subject is exporting audit logs. But the question also contains two conditions: the answer has to apply to administrators, and it has to apply to the cloud product.

A procedure written for on-premises customers (not using the cloud version) can use nearly identical language and still be the wrong answer for those folks. So can a procedure written for end users instead of administrators. Both can look highly relevant to a search system while failing to satisfy what the question askers actually require.

Those conditions — role, deployment, and dozens of others like them — are query constraints. Oracle describes search constraints as a way to limit the search space within an index. Firebase defines a constraint as something used to narrow the set of documents a query returns.

The concept isn’t new. What’s changed is what happens when the wrong constraint slips through undetected.

Read more

The garage is what I kept looking at. The opening at street level seemed to drop back farther than a single level of parking should allow. I sat there wondering whether I was looking at two stacked levels underneath the house. I don’t know enough about the city’s building limits to say whether that’s even possible. After thinking about it, I decided I was probably looking at a vertical car-stacking lift, a system that lets one garage opening hold twice the cars it appears to hold. Noe Valley has enough wealth concentrated in three-story Edwardians that this kind of luxury home improvement isn’t much of a stretch.

I’d been in a meeting in Silicon Valley earlier that morning about content operations for a tech writing team. The longer I watched, the more my brain started making connections between what I was seeing and what we’d discussed earlier — that’s just how my crazy brain works, jumping between unrelated things until sometimes, if I’m lucky, something clicks.

As I watched the improvements being made to prepare the house to withstand an earthquake it struck me that using this metaphor might be a useful way to help organizations understand why they need to think about retrofitting their content for AI.

Read more

Deterministic system (noun)

A system whose rules produce the same output whenever it receives the same inputs under the same operating conditions.

About Deterministic Systems

Deterministic systems follow rules that determine what happens. Start with the same state, feed in the same inputs, and the system applies the same rules, resulting in the same result every time.

A calculator is the simplest example.

Enter 10 × 5 and you get 50, every time.

Software permissions work the same way. If access depends on a user's role, subscription level, and security settings, the system reaches the same decision whenever those values match.

Same inputs covers more than what our users type in. It includes things like account settings, stored data, software version, current time, feature flags, and information pulled from connected services. Change any one of those inputs, and our result can change too.

What Makes A System Deterministic?

Subscribe now

Read more

A few cycles in, something strange happened. Long before an IV line was prepped, the beeping of a medical device — or something else — reminded me of my experiences in the cancer ward. That reminder would immediately trigger acute anxiety.

I hadn’t had any chemo administered, and yet, I was already feeling as if I had. My oncologist had a name for it: anticipatory response. My brain had associated specific sounds, smells, and situations with treatment. Those anticipatory cues were enough to trigger the response before any treatment began.

Years later, watching technical documentation teams adapt to generative AI and automated answer engines, I keep coming back to that experience. It made me more interested in what readers learn to expect from documentation before they have processed much of the page.

The Brain As An Expectation Engine

The human brain is an organ that continually monitors signals that are associated with prior experience to anticipate threats. That’s the pattern I noticed in the hospital, and it gave me a useful way to think about what readers of our documentation bring with them on their journey to find answers to their product use questions.

Subscribe now

Read more

Researchers at Ericsson were testing retrieval-augmented generation (RAG) against technical documents. One of their discoveries was that keywords appearing closer to the beginning of a sentence were retrieved by AI tools with high accuracy. Keywords appearing later in sentences were harder for AI to retrieve accurately.

Before The Model Answers Anything

The paper, Observations on Building RAG Systems for Technical Documents (PDF download at end of article), was written by Sumit Soman and Sujoy Roychowdhury. The researchers tested technical info from IEEE wireless networking specifications and a battery terminology glossary — reference documents, not how-to step-by-step instructions. They examined factors including chunk length, retrieval method, definitions, and keyword position.

Their keyword-position findings:

1. Keywords closer to the beginning of a sentence are retrieved with high accuracy.

2. Keywords appearing later in a sentence were more difficult to retrieve.

Subscribe now

Read more

Chances are good you’ve seen this behavior before. And, if you’re like me, you might not know why.

Where Web Previews Come From

The visualization that platforms like Slack, Facebook, and BlueSky generate when you paste a hyperlink is supposed to contain the same info humans see when they visit the page the link points to. Looking into why that doesn’t always occur led me to a separate layer of metadata in a page’s <head>, and to a specification called the Open Graph protocol.

Introduced by Facebook in 2010, Open Graph provides a universal format for web publishers to control precisely how their URLs and website content are displayed when shared across social networks and messaging platforms. It gives web publishers a way to specify a title, description, image, and other info that platforms can use to determine what content will display in a link preview.

What Was Broken

In the Slack example, the image was the first thing I noticed missing. No event photo appeared in the card, the way it did on the web page I visited. The copy didn’t discuss the conference. Instead, it showed a description of the event production company.

The headline was accurate. It displayed the conference name and dates, but the rest of the content was a mismatch.

One Possible Explanation

The site’s template may explain it. When page-level Open Graph values aren’t supplied, a web page preview may fall back to the site-wide default, producing generic copy about the organization that owns the site, instead of anything specific to the event they were promoting.

An Assumption That Needs Some Scrutiny

Increasingly, web-based documentation includes a share button to help users easily distribute our content to others. When someone clicks the share button they likely assume the shared link will display the content correctly wherever it lands.

But, that assumption doesn’t always hold true.

Tech writers typically check published output in the channels we control.

• A PDF user manual gets reviewed as a PDF file.

• Our help site gets checked for the experience users will have when they access that information using a web browser.

Shared link previews, on the other hand, are seldom discussed in tech comm circles and aren’t commonly included in pre-deployment review. That needs to change because they impact the customer experience. Link previews deserve scrutiny and to become part of our publication workflow quality control process.

The “Big Three” Tags For Writers

While there are dozens of Open Graph tags covering everything from video durations (video:duration) to property types (og:type), tech writers need to pay attention to three fundamental properties.

Here is what they look like in the markup, and how to approach writing them.

1. The Title (og:title)

This is HTML markup that controls the bold headline of your preview card.

While it is tempting to just map this directly to your <title> or <h1> tag, your og:title should be optimized for standalone context. A page in your doc portal site might be titled “OAuth Tokens” because it lives under an “Authentication” breadcrumb. But stripped of that breadcrumb in a Slack channel, “OAuth Tokens” is vague. Your og:title should be descriptive and independent.

2. The Description (og:description)

This is the one-to-two sentence summary that appears below the title.

Unlike a traditional SEO meta description (which is written to for search engine algorithms), an og:description is a direct pitch to a human being in a chat window. Keep it punchy and action-oriented. Aim for under 100 characters to ensure it doesn’t get truncated on mobile devices or smaller chat windows. Do not just let your site generator pull the first paragraph of your page—that often results in awkwardly cut-off sentences or code snippets being displayed as text.

3. The Image (og:image)

This points to the image file that will serve as the banner for your preview card.

This approach requires a bit of collaboration with your design or frontend web team, but the content strategy belongs to you. Don’t settle for a generic company logo image across all 5,000 pages of your documentation. Advocate for a dynamic image generation system, or create standard, topic-specific banners (e.g., a specific banner for “Tutorials,” another for “Reference,” and another for “Release Notes”).

Testing Your Link Preview Metadata

We don’t have to wait until a page is pushed to see how our Open Graph tags perform. Once our markup is staged, we can use one of several free validators to preview how our content will look:

• opengraph.xyz: A great all-in-one tool that shows how our link will render across Slack, Discord, LinkedIn, and Facebook simultaneously.

• LinkedIn Post Inspector: Excellent for verifying that our business-critical docs are caching correctly on professional networks.

Take Ownership Of Documentation Previews

As tech writers, we often advocate for improvements in customer experience. We meticulously structure our docs, use markdown or DITA to ensure information is accessible, accurate, and scannable.

Taking control of Open Graph metadata extends our advocacy one step further. By treating og:title and og:description as distinct, valuable content types, we can help ensure that the quality of our documentation experience is up to par regardless of where consumers encounter it. 🤠

Join Bill Raymond for Practical AI at Work: Let’s Tour the New ChatGPT App, a free, live, one-hour educational session on September 9, 2026, at 12 noon PT.

Register for free workshop

Sponsored by Cambermast.com training and the Bill Talks AI newsletter, in partnership with The AI Collective and The Content Wrangler.

A practical orientation

A task can start with a quick question, become a larger project, or involve building or improving software. The new ChatGPT desktop app supports all of these types of work. The best place to start depends on what you need to do.

In this live Practical AI at Work session, Bill Raymond will tour the app through three practical questions:

• What are you trying to accomplish?

• What context does the work need?

• Where will you review the result?

Using one realistic workplace request, Bill will demonstrate how those questions can guide the choice of workflow.

Discover Four Areas of The New ChatGPT APP

The session will explore four areas of the new ChatGPT app:

1. Chat — Quick questions, thinking, research, and conversation

2. Work — Longer, multi-step tasks and reviewable deliverables

3. Codex — Work that calls for building or improving software

4. Plugins — Workflows that may benefit from additional skills or connected apps, after you understand access and approval requirements

By the end of the session, you’ll have a simple way to choose Chat, Work, Codex, or a plugin-supported workflow, along with a practical understanding of the features in the new ChatGPT app.

Why Tech Writers Should Attend

Tech writers routinely move among questions, research, source material, drafts, reviews, deliverables, and collaboration with subject-matter experts and software teams. While this workshop is a general orientation to the new ChatGPT app (not a technical-writing course) it offers a useful opportunity to see how the app distinguishes among different kinds of workplace tasks.

What To Expect

Feature access can vary by ChatGPT plan, workspace settings, role, region, and connected-app permissions. This session will provide an orientation and decision method; it does not promise that every participant will have the same options enabled.

Practical AI at Work: Let’s Tour the New ChatGPT App
September 9, 2026 · 12 noon Pacific Time
Free, live, one-hour educational workshop

Attending this free ChatGPT workshop is also an opportunity for you to see Bill Raymond teach. Bill is The Content Wrangler’s AI Training Partner, and we highly recommend his instructor-led training for tech writers and related content pros who want practical guidance for putting AI to work.

Tech Writing-Specific Training Workshops

While the free app workshop provides an introduction to Bill’s teaching approach, if you want more focused, guided instruction aimed specifically at professional content creators, consider registering for his upcoming AI Workshop for Tech Writers and Content Creators (Fall 2026). Classes start September 15, 2026.

💰 You can save 10% off the cost of registration when you use discount code — TCW — at checkout.

Learn More About Tech Writer AI Workshop

That’s why you should consider registering for the Mastering API Documentation with AI course taught by API documentation expert, Mark Wentowski, founder at Docs Geek.

Designed specifically for tech writers, developers, and product managers, this 7-week live virtual bootcamp bridges the gap between theory and practical application.

Why You Should Take This Course

1. Hands-On, Real-World Skills

This isn’t a high-level theoretical overview. You’ll get your hands dirty (figuratively speaking) with the exact tools the industry relies on to produce API Docs.

Over seven sessions, you’ll master:

• Making API requests using cURL and Postman

• Structuring data with JSON

• Writing and troubleshooting OpenAPI and YAML in Swagger Editor

• Identifying user journeys and mapping them into sequence diagrams using Mermaid

2. The “AI Add-On” Advantage

What sets this cohort apart is its forward-looking approach to using AI to produce API Docs. A brand-new (optional) AI module teaches you to use Claude directly inside a GitHub Codespace (no complex local setup required!).

You’ll learn how to draft API flow guides, generate OpenAPI descriptions, and perhaps most importantly, validate AI output against actual API behavior so you aren’t misled by so-called hallucinations.

3. Walk Away With A Portfolio Piece

You’ll walk away with proof of your capability. The course includes hands-on assignments and a final project where you will build and submit a complete API documentation portal for peer review.

If you’re looking to break into API documentation creation, this portfolio piece is exactly what hiring managers are looking for.

4. Flexible for Working Professionals

The Fall 2026 cohort kicks off on Monday, October 19 at 8:00 AM PT. While it’s highly recommended to join the weekly 90-minute live sessions to participate in code-alongs and ask questions, full class recordings are provided for on-demand viewing.

Have a schedule conflict? No worries. Follow along at your own pace asynchronously without falling behind.

5. Pay For The Class In Installments With Klarna

Prefer to spread the cost of the class? Klarna is available as a payment option at checkout, letting you split your enrollment fee into interest-free installments.

Ready To Future-Proof Your Tech Writing Career?

Seats for this cohort are limited and fill up fast. Don’t delay. Reserve your seat today!

Save $250 off the cost of class registration when you use discount code — TCW — at checkout.

Register Today!

Inference gap (noun)

A fact, condition, relationship, exception, or consequence that an audience needs but the content doesn’t explicitly state.

What Creates Inference Gaps?

Tech docs can be 100% accurate and still leave readers (and machines that access our content) completely in the dark. Sometimes an important fact is missing. More often, however, the writer understands exactly how the system works but fails to put those connections in our docs.

They leave out unwritten rules, like:

• who a policy applies to

• when it kicks in

• what the exceptions are, or

• how flipping one switch changes something else

When these connections in our content are missing, readers (human or otherwise) are forced to fill-in-the-blanks by guessing. A human might rely on trial-and-error, past experience, or interface clues. An AI tool will try to stitch scattered sentences together and invent an answer.

Guesswork is a problem when it changes how someone understands our instructions or makes them uncertain what action they should take or what happens if they get something wrong. We don’t have to explain every possible detail imaginable (that’s not a practical solution), but we need to connect-the-dots clearly enough that readers don’t have to guess to get a reliable answer.

Common causes include:

Subscribe now

Read more

The AI Workshop for Content Creators, led by Bill Raymond, in partnership with The Content Wrangler, is designed to help close that gap.

This seven-week, live, instructor-led online workshop gives tech writers (and other content pros) a structured way to apply AI across research, planning, drafting, editing, and quality review. You won’t spend seven weeks watching demo videos masquerading as training. Instead, you’ll build prompt libraries, custom GPT instructions, evaluation checklists, and a plan for putting AI-assisted content production into practice. And Bill will be there to help you along the way.

Learn More and Register

The curriculum (see the week-by-week workshop breakdown at the end of this post) addresses problems tech doc teams already face:

• identifying content gaps

• understanding audience needs along their journey

• maintaining a consistent voice across doc sets

• accelerating content inventories and audits

• prioritizing improvements, and

• establishing editorial controls

The workshop also covers ethical guardrails and governance expectations, subjects that deserve more attention as AI becomes part of routine documentation production.

Each student develops a real-world individual or team project throughout the workshop. By the final session, you should have a repeatable workflow you can continue using and improving.

The workshop runs Tuesdays from September 15 through October 27, 2026, from 10 a.m. to noon Pacific time. Sessions are live and online, and participants receive a certificate of completion.

If you’re ready to move from occasional AI experimentation to a working system for producing and improving content, review the workshop details and register.

Curriculum

Learn More and Register

Inference load (noun)

The amount of unstated information a person or machine must supply to understand content, connect related facts, or decide what to do.

About Inference Load

What Creates Inference Load?

Inference load is created when technical documentation leaves important relationships implicit. Readers and AI systems must determine how facts fit together, whether a rule applies, and what conclusion the content supports. Neither people or machines are particularly good at that.

What Inference Load Looks Like

Read more