Documentation in the Age of AI

Why We Should View Docs as a Product

Scan to open the talk page

Start with the user

Who reads your docs?

And what counts as “reading”?

When people read docs

The documentation page was the experience.

How people use docs now

The path now has an intermediary.

A person asks. An agent consults the docs. Then the agent or person acts.

The wider web

Docs traffic · GitBook

Docs traffic · Mintlify

Why quality matters

Bad docs become bad actions.

The agent follows the wrong path. The task fails. The user feels the frustration.

Docs as product

What that looks like in practice.

  1. 01Own itA product owner for docs; PMs and engineers own the truth
  2. 02Draft it efficientlyLow-friction drafting: agentic tooling, human in the loop
  3. 03Keep it correctAutomated checks in CI (spectral for OpenAPI) before publish
  4. 04Make it reachablellms.txt, MCP, and pages you can copy as Markdown (.md)
  5. 05Learn and improveAnalytics, user feedback, and a maintenance roadmap

Docs as product

The system and content need different owners.

Docs product ownerOwns the systemInfrastructure, publishing, agentic authoring tools, discovery, and usability
Feature PMs + engineersOwn the contentAccuracy, initial drafts, and maintenance as the product changes

Docs as product

Start with a user and a task.

Then measure whether they can complete it.

A request≠A completed task

The same task must succeed for a human and an agent.

A practical workflow

Use AI to draft, not to decide.

AI toolsDraft
Truth ownersReview
CI checksValidate
Docs systemPublish
Truth ownersMaintain

Human and agent access

Keep one source of truth. Serve every reader.

For peopleUsable site docsBrowse, search, ask AI, and view or copy pages as Markdown.
Source of truthCanonical documentationVersioned, reviewed, maintained, with changelogs.
For agentsUseful access pathsllms.txt · llms-full.txt · .md pages · MCP tools

Docs as product

Let real use shape the roadmap.

MeasureTrack usage and outcomesTop searches, and whether AI chats actually answer, or come up empty
ListenAct on feedbackCapture it and ship it, crediting the community
ImprovePlan the workA maintenance roadmap that keeps every task doable, for agents and people
Scan to open the talk page

Treat documentation as a product.

Own the system. Maintain the truth. Measure task success.

Chris Nowicki

Chris Nowicki

DevEx Engineer / Documentation Product Manager at Commerce

@iamwix