Writing About AI

Why Is Documenting AI Different From Documenting Other Software?

AI documentation frequently falls short because traditional documentation practices were designed for deterministic systems: systems that do the same thing every time, return predictable outputs, and can be fully described by listing their states and transitions. AI systems don’t work that way. They produce outputs that vary, fail silently, and behave differently depending on inputs that users can’t always see or control.

When you apply deterministic documentation patterns to non-deterministic systems, you get docs that are technically accurate and practically misleading. Users follow the steps. The product doesn’t do what the steps implied. Trust erodes not in the documentation, but in the product.

I created this series to help close that gap.

What Does Good AI Documentation Actually Do?

AI documentation isn’t a specialized niche. It’s a new set of constraints on a job that already existed.

Writing clearly about what a system does, why it behaves the way it does, and what users should expect from it. That’s always been the job. AI makes it harder because the answers to those questions are less stable, less certain, and less visible than they are for conventional software.

Three things shape how this series approaches that challenge:

1. Documentation shapes what users believe about AI — whether you intend it to or not. Every word you choose about an AI feature teaches users how to model it. “The AI will suggest” implies fallibility. “The AI generates” implies production. “The AI decides” implies authority. None of these are neutral. Writers who don’t think carefully about language become accidental translators of AI behavior, often inaccurate ones.
2. AI features don’t need to be demystified. They need to be described accurately. There’s a tendency in AI documentation to either oversimplify (“it learns from your data”) or over-explain (“using transformer-based large language model architecture”). Neither serves users. The question isn’t how much to say about the underlying system but what users actually need to know to act confidently and set appropriate expectations.
3. The limits matter as much as the capabilities. Most AI documentation focuses heavily on what a feature can do and says very little about what it can’t, what it won’t, or what it might get wrong. That imbalance is a documentation failure that transfers risk from the product to the user. Honest documentation of AI behavior is the foundation of user trust, not a threat to it.

This series doesn’t promote AI or argue for its value. It exists to help writers explain AI systems as they actually behave in real products.

Who Is the Writing About AI Series For?

This series is for technical writers who are documenting products or features that use AI regardless of whether they have a background in machine learning. You don’t need to understand how a model is trained. You do need to explain what it does, how it behaves, and what users should and shouldn’t expect from it.

It’s also useful if you’re encountering AI concepts in your documentation work for the first time and need a framework for thinking about them before you start writing.

What This Series Does Not Cover

This series does not focus on how AI is built, trained, or evaluated. It excludes machine learning theory, AI tools for documentation, and product-specific API references. These topics remain intentionally out of scope—not because they lack value, but because they belong to distinct professional domains.

How Is the Writing About AI Series Organized?

The series moves from conceptual grounding to practical application across three layers:

Conceptual articles help you think about AI at the product and system level before you write a single sentence of documentation.

AI Product Landscape articles describe the major categories of AI features, such as what they are, how they behave from a user’s perspective, and where the documentation challenges are specific to each type.

AI Documentation Guides are the applied layer. How to actually write about each category in practice, what to include, what to avoid, and how to handle the parts of AI behavior that don’t fit standard documentation patterns.

You can read in order or go directly to the category you’re working on.

What Articles Are in the Series?

Getting Started Writing About AI

A guide to navigating the Writing About AI series

Understanding AI Through Goals, Tools, and Overlap

Why AI is so hard to define

AI Product Landscape

A Technical Writer’s Guide to the AI Feature Categories That Matter

Understanding AI Safety and Guardrails Across Audiences

AI Documentation Guides

How to write about each AI category in practice.

Where Should I Start in the Writing About AI Series?

If you’re new to this series, begin with Getting Started Writing About AI.

If you already know what type of AI feature you’re documenting, go directly to the relevant AI Product Landscape article and its paired documentation guide.

If you’re looking for general technical writing principles that apply across all documentation work, see Technical Writing Best Practices.

---

The Doc Landscape is a reference platform for technical writers navigating modern software environments. This series is written from practitioner experience — not theory.