That’s exactly why you need to check out the Mastering API Documentation with AI course by Docs Geek head-honcho, Mark Wentowski, who helps API developers around the globe explain their solutions to audiences that seek to understand how they work.

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

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

Register today!

Here is why this course is the perfect catalyst for your career:

1. Hands-On, Real-World Skills

This isn’t a high-level theoretical overview. You will be getting your hands dirty with the exact tools the industry relies on. 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.

• Mapping 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 AI. A brand-new, optional AI module lets you 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 (crucially) validate AI output against actual API behavior so you aren’t misled by hallucinations.

3. Walk Away with a Portfolio Piece

You won’t just leave with knowledge; you’ll leave with proof. 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 trying to break into API writing, 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 90-minute live sessions to participate in code-alongs and ask questions, full recordings are included with every enrollment. If you have a schedule conflict, you can follow along asynchronously without falling behind.

Ready to future-proof your tech writing career? Seats for this cohort are limited and fill up fast.

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

Flexible installment payments are available via Klarna at checkout).

Notifications aren’t able to reach me easily on the mountain trail, and yet, my phone still proves helpful on these adventures. I use it as a compass, to take photos, listen to music, and to capture ideas that pop into my head like the aforementioned a-ha moment.

As the idea percolated around in my brain, I reached for my phone to save it. Through my polarized sunglasses, the screen looked almost blank. I knew what was happening. I had researched this phenomenon before and understood the polarized lenses were interfering with my ability to see the display.

I dictated the note instead.

The same thing has happened on sun-filled days at the pool and while bicycle riding. When the screen becomes hard or impossible to read, voice is easier than taking off my sunglasses, finding my prescription readers, and attempting to correctly type a message.

I’ve noticed similar choices about voice input among friends. Some say they use voice because changes in their vision make screens difficult to read. Others say they dictate messages because they’re often outside in bright light and have the same challenge as I did that day on the mountain. Others just prefer talking to typing.

Those observations are anecdotal, of course, but they gave me a question to investigate.

Read more

Verifiability (noun)

The extent to which a claim can be checked against evidence to determine whether it is correct under the stated conditions.

About Verifiability

Suppose our product guide says: “Administrators can restore deleted projects within 30 days.”

Our customer asks whether the policy applies to projects deleted from their trial account. Our writer finds the same restoration info in several places, but none of them tells them which account types our policy covers; nor does it tell them why the limit is 30 days.

Before confirming the information, our writer needs evidence specifically about restoring projects from trial accounts. That evidence might come from our product specifications, test results, or the product subject matter expert responsible for the feature.

Verifiability means checking whether a claim is true. A statement can be correct, and at the same time, hard to verify (if no supporting evidence is available).

Why Tech Writers Need to Understand Verifiability

Read more

The subject? Enterprise data systems. The problems it identified sounded familiar:

• info scattered across systems

• unstructured content that’s difficult for AI to use

• missing context and semantics, and

• unclear relationships between info and the situations to which it applies

The Access Problem

In early 2026, MIT Technology Review Insights surveyed 300 senior leaders in data, technology, product, and AI roles. It also interviewed execs to add context to the survey results. Most respondents worked for big organizations with annual revenues of $500 million or more.

Survey respondents said their AI systems can access, on average, only 45% of their organization’s data. Given how messy corporate content can be, I expected a low number; but 45% feels less like a statistic and more like an indictment.

Researchers call those orgs whose AI can access 30% or less of their data “data laggards.” A smaller group says its AI systems can access more than 70% of enterprise data, and those same orgs also say they’re seeing success with AI agents.

The Obstacles

Read more

Retrievability (noun)

An enabling capability that determines whether a retrieval system can locate and return the right content for a given query.

Suppose our docs include the correct procedure, but the way we present the additional information needed obscures the right answer.

Perhaps the heading we chose reads “Exporting data” and the name of the product sits near the top of a long page of procedural info. And, the cloud-only restriction lives in a note.

If an AI retrieval system searches thru short passages from our docs, it may retrieve the procedure without the detail that says it applies to the cloud version. Or, perhaps it accesses the step-by-step instructions without finding the note that qualifies it. As a result, a similarly worded procedure for on-premises users may be referenced to generate an answer instead.

Even when the correct answer appears in our docs, unclear wording or poor content organization choices can make it harder for a retrieval system to differentiate it from other similar procedures.

Writers shape how documentation reads and how it’s organized, including the metadata attached to it. The retrieval system determines what gets indexed and how a query is matched against it.

Why Tech Writers Must Understand Retrievability

Clear writing alone can’t resolve the kind of gap the audit-log example shows. If retrieval never surfaces the right passage, no amount of good writing fixes what the model never saw.

We tech writers make all sort of choices a retrieval system can find. In the audit-log example, using the heading “Exporting data” is one of those choices. A specific task name gives the system more context when it looks at that passage by itself.

The same is true of consistent terminology that distinguishes similar features and applicability statements that clearly identify a cloud-only restriction, rather than relegating it to a separate note elsewhere in the docs.

Understanding retrievability helps us see that the answer can be in our docs but still fail to appear when someone needs it. Finding out why it fails may require us to work with customer support teams or the others who manage search and AI systems.

We bring our knowledge of the documentation: which procedure answers the question and the conditions under which it applies. When we can see real user questions and the system’s results, we can use that knowledge to investigate specific failures.

What Retrievability Looks Like In Documentation

Read more

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. 🤠