Technical writing and the era of AI agents

AI agents are only as useful as the knowledge they can access. When documentation is incomplete, imprecise, or poorly structured, agents don't stop – they happily fill the gap with outdated training data or a competitor's product. This month, we look at the implications for technical writers, and how we design Zensical for both humans and agents from the ground up.

Read on to learn about the tools we're building to serve humans and agents alike, and what we shipped in April, including macros, link validation, and strict mode.

How agents read your documentation

Humans are forgiving readers. We skim, infer, and fill gaps with context accumulated over time. Agents don't work that way. They treat everything they're given as signal, can't skip what doesn't matter, and when they hit ambiguity, they don't pause, they guess. Every unnecessary sentence degrades the agent's output. Every ambiguous term is an invitation to hallucinate.

Agents don't change what good documentation looks like. They make the cost of falling short impossible to ignore, and reveal something in the process: the practices behind great documentation – single-sourcing, topic-based authoring, precise terminology, clear structure – turn out to be exactly what agents need.

Teams that have invested in rigorous documentation structures are sitting on something increasingly valuable. The expertise behind that content – knowing what matters, how to structure it, how to make it precise – is something agents depend on but can't replicate. The question is whether teams have the tooling to surface it.

What we're building and why

The tools we're building put your expertise at the center. We've laid out our thinking on what agentic workflows demand from documentation tooling in ZAP 009, published in full and freely accessible. The core argument:

In May, we're releasing Disco CLI exclusively to our Zensical Spark members, giving agents direct, structured access to your documentation so they can query, filter, and retrieve exactly what they need. It works with your existing project and workflows, no changes to your content required.

Disco CLI gives agents structured access to your documentation

This is the first step toward a fully integrated documentation stack, where topic-based authoring, docs-as-code, and agent-ready content delivery work together.

What we shipped in April

We have heavily invested in feature parity: eight new versions shipped in April, bringing Zensical closer to full compatibility with the MkDocs ecosystem.

Macros

Macros let you define custom variables and functions directly in your Markdown files, making it easier to manage and reuse content across your documentation. Our new Python Markdown extension provides the same functionality as the mkdocs-macros plugin, and includes a configuration shim for zero-effort migration from MkDocs.

Macros got even better – as they are implemented as a Python Markdown extension, macros now also work inside Python docstrings, so you can use them when building API documentation with mkdocstrings. Previously, this required clumsy workarounds.

Link validation

Zensical now validates all internal references at build time and reports issues with precise source locations, so broken links or footnotes don't make it into your published documentation. Validation is enabled by default, no changes required. It's quite likely that you'll run into at least some warnings – as we did – since before, it was easy to miss unused link definitions or unresolved references.

Unresolved link references include precise source locations

While MkDocs only validates links and anchors, Zensical checks the full lifecycle of a reference, warning about unresolved references and unused definitions. This includes inline links, reference-style links, link definitions, anchor targets, and even footnotes.

Strict mode

The new strict mode allows you to abort the build when warnings are detected, so you can enforce link integrity and prevent broken links from being published.

GLightbox

Zensical now includes support for GLightbox, adding image zoom and gallery features to your documentation. Unlike the mkdocs-glightbox plugin, which reparses the full page, our implementation uses Python Markdown's native extension API – making it significantly faster and less memory-intensive.

Installable themes

You can now bundle theme overrides into installable packages and distribute them via pip. Existing Material for MkDocs theme derivations run on Zensical with minimal changes. This is the first step toward component-level theme reuse – something we'll make considerably more flexible once the component system arrives.

For organizations managing dozens or hundreds of projects, packageable themes are incredibly useful for sharing theme overrides and configuration internally.

In other news

What's next

Feature parity remains our near-term focus – we'll continue porting the most essential Tier 1 and Tier 2 MkDocs plugins to Zensical. In parallel, we're tackling one of the longest-standing divisions in documentation tooling: topic-based authoring and docs-as-code have existed in separate worlds for too long.

Together with our Zensical Spark members, we'll be iterating on Disco CLI, building toward documentation that serves humans and agents equally well.

Your voice matters

Questions, thoughts, or anything on your mind – hit reply. We read everything.