How to use AI-first workflows to maintain technical docs 20x faster

Original post

Learn how Distributional uses Claude Code and GitBook to maintain technical documentation 20x faster while catching issues humans miss. A practical AI-first workflow.

Guest post by Scott Clark, CEO of Distributional

A year ago, updating our technical documentation at Distributional meant blocking out hours for careful review, proofreading, and cross-checking. Today, that same work takes minutes. Our AI-first documentation workflow is literally 20 times faster — and it catches issues that previously required diligent human review and often got missed anyway.

The difference? We’ve integrated Claude Code directly into our GitBook workflow, creating a system where AI handles the tedious work while we maintain control over the final output.

Here’s how we do it.

The three-step workflow

Our documentation flow is deceptively simple. It combines GitBook’s Git Sync with Claude Code’s agentic capabilities to create a system that’s both powerful and maintainable.

1. Connect GitBook to GitHub

We use Git Sync to keep our documentation automatically updated based on what’s in our repository. This creates a single source of truth where changes flow automatically from code to docs.

2. Point Claude Code at the repository

This is where things get interesting. Claude Code is a command-line tool that lets you delegate coding tasks directly from your terminal. Instead of manually editing documentation files, we give Claude Code plaintext instructions about what we want to accomplish.

3. Review, push, and merge

We quickly review the diff to make sure the changes make sense, push a dev branch for team review, and merge. The entire process takes minutes instead of hours.

What we ask Claude Code to do

The real power of this workflow comes from the breadth of tasks you can delegate. Here are some of the prompts we use regularly:

Quality assurance prompts

• “Look through the entire documentation for typos, grammatical errors, and broken or missing links. Fix them.”

• “Review the documentation for clarity and precision, suggest edits.”

• “Look at our SDK repo and make sure none of our example code is out of date in the docs.”

Content generation prompts

• “Read the entire documentation and create a FAQ of the top 30 potential questions with 2–3 sentence answers linked to the appropriate docs in an expandable list format grouped by topic.”

• “Make a glossary in the reference section for any unique terms, define them in 1–2 sentences and give links to the source document pages within the docs.”

AI optimization prompts

• “Suggest edits to the documentation that would make it more accessible for a coding agent to implement our solution or AI chat interface asking how to use our product.”

And of course, the meta-prompt we gave to multiple AI tools: “What prompts should I give a coding agent to improve the technical documentation of my product?”

Why we keep humans in the loop

Despite how well this system works, we still maintain careful human review for every change. There are good reasons for this:

The hallucination risk

This is the obvious one — LLMs can hallucinate features that don’t exist or haven’t been released yet. Accuracy is one of the most important factors for documentation, and so you’ll want to have a human checking to make sure that your docs reflect your actual product.

The mean regression problem

Like all language models, Claude wants to create documentation that fits existing patterns. It will naturally drift toward boilerplate structures and conventional formats, even when your product needs something more unique. Human review ensures your documentation maintains its distinctive voice and accurately represents what makes your product different.

The over-generation tendency

AI loves to generate text. Not every docs page needs a troubleshooting section explaining how to pip install your SDK. Sometimes less is more, and humans are better at recognizing when documentation is complete versus when it’s just comprehensive.

Level up: Using system prompts for consistency

Once you’re comfortable with the basic workflow, you can take it further by setting up system prompts (also called custom instructions) that apply to every documentation task. This is particularly useful for enforcing style guides and formatting conventions without having to repeat them in every prompt.

For example, you can use system prompts to maintain consistency across your docs:

With this in place, Claude Code automatically applies these rules to every edit it makes, whether it’s fixing typos, generating FAQs, or creating new content. You can update your system prompt as your style guide evolves, ensuring all AI-generated content stays aligned with your documentation standards.

The result: less time correcting formatting inconsistencies, more time ensuring your content is actually helpful.

What this means for documentation teams

This workflow represents a fundamental shift in how technical documentation gets maintained. Instead of dedicating large blocks of time to mechanical tasks like link checking, typo fixing, and consistency reviews, documentation teams can focus on higher-level work: information architecture, user research, and strategic content planning.

The AI handles the tedious work with superhuman attention to detail. The humans handle the creative work that requires judgment, taste, and product knowledge.

Getting started with an AI-first docs workflow

If you want to implement a similar system, here’s what you need:

1. **GitBook with Git Sync enabled** — This creates the foundation for version-controlled documentation that updates automatically.

2. **Claude Code or similar agentic coding tool** — You need a tool that can read and modify files based on natural language instructions.

3. A clear review process — Define what requires human review and what can be automatically merged. Start conservative and adjust as you build confidence in the system.

4. Good prompts — Start with the prompts we’ve shared here, then iterate based on your specific documentation needs.

Editor’s note: Since Scott wrote this article, we’ve published a skill.md file for GitBook that teaches AI agents the best way to format content for GitBook compatibility. It doesn’t just help you build your docs consistently with AI, it also improves the output.

The future of documentation work

We’re still early in figuring out how AI fits into documentation workflows. But one thing is clear: the tedious, mechanical parts of maintaining docs can increasingly be automated. That doesn’t mean documentation teams become less important — it means they can focus on the work that actually requires human judgment.

What remains is the creative work of understanding your users, structuring information effectively, and ensuring your documentation actually serves the needs of the people using your product. These are problems that require personas, user research, and strategic thinking — all areas where GitBook provides excellent tools to support your work.

The AI handles the grunt work. You handle the strategy. And together, you create documentation that’s both high-quality and maintainable.

Want to implement an AI-first documentation workflow? Sign up for GitBook and start building documentation that’s faster to maintain and easier to keep up-to-date.

Related resources

→ How to optimize your docs for AI search and LLM ingestion

→ GitBook’s Git Sync documentation

→ Build your docs around your users’ needs with documentation personas

New post with notes mentioning skills, MCP, CLI:

Learn how Distributional uses Claude Code and GitBook to maintain technical documentation 20x faster while catching issues humans miss. A practical AI-first workflow.

Guest post by Scott Clark, CEO of Distributional

Editor’s note: This began as a guest post from Scott Clark, CEO of Distributional, and the AI-assisted documentation workflow he describes still works exactly as written. Since he wrote this article, we’ve shipped a few more ways to run those workflows — a GitBook MCP server and a CLI for connecting agents to your content, expanded skill files, and GitBook Agent, an AI teammate that works directly in the editor if you’d rather not touch a terminal at all. We’ve noted where each fits below.

A year ago, updating our technical documentation at Distributional meant blocking out hours for careful review, proofreading, and cross-checking. Today, that same work takes minutes. Our AI-first documentation workflow is literally 20 times faster — and it catches issues that previously required diligent human review and often got missed anyway.

The difference? We’ve integrated Claude Code directly into our GitBook workflow, creating a system where AI handles the tedious work while we maintain control over the final output.

Here’s how we do it.

The three-step workflow

Our documentation flow is deceptively simple. It combines GitBook’s Git Sync with Claude Code’s agentic capabilities to create a system that’s both powerful and maintainable.

1. Connect GitBook to GitHub

We use Git Sync to keep our documentation automatically updated based on what’s in our repository. This creates a single source of truth where changes flow automatically from code to docs.

Editor’s note: Git Sync is still a great foundation, and it’s now one of a few ways in. If you’d rather not sync to a repo, you can connect an agent straight to your content — see Build with AI.

2. Point Claude Code at the repository

This is where things get interesting. Claude Code is a command-line tool that lets you delegate coding tasks directly from your terminal. Instead of manually editing documentation files, we give Claude Code plaintext instructions about what we want to accomplish.

3. Review, push, and merge

We quickly review the diff to make sure the changes make sense, push a dev branch for team review, and merge. The entire process takes minutes instead of hours.

Editor’s note: There are now two purpose-built ways to give an agent access to your GitBook content. GitBook MCP connects an AI agent to the GitBook API to create, edit, and manage docs, and the GitBook CLI does the same from the terminal — a natural fit for the Claude Code setup Scott describes. (Both are distinct from the read-only MCP server GitBook exposes on published docs for end-readers.)

What we ask Claude Code to do

The real power of this workflow comes from the breadth of tasks you can delegate. Here are some of the prompts we use regularly:

Quality assurance prompts

• “Look through the entire documentation for typos, grammatical errors, and broken or missing links. Fix them.”

• “Review the documentation for clarity and precision, suggest edits.”

• “Look at our SDK repo and make sure none of our example code is out of date in the docs.”

Content generation prompts

• “Read the entire documentation and create a FAQ of the top 30 potential questions with 2–3 sentence answers linked to the appropriate docs in an expandable list format grouped by topic.”

• “Make a glossary in the reference section for any unique terms, define them in 1–2 sentences and give links to the source document pages within the docs.”

AI optimization prompts

• “Suggest edits to the documentation that would make it more accessible for a coding agent to implement our solution or AI chat interface asking how to use our product.”

And of course, the meta-prompt we gave to multiple AI tools: “What prompts should I give a coding agent to improve the technical documentation of my product?”

Why we keep humans in the loop

Despite how well this system works, we still maintain careful human review for every change. There are good reasons for this:

The hallucination risk

This is the obvious one — LLMs can hallucinate features that don’t exist or haven’t been released yet. Accuracy is one of the most important factors for documentation, and so you’ll want to have a human checking to make sure that your docs reflect your actual product.

The mean regression problem

Like all language models, Claude wants to create documentation that fits existing patterns. It will naturally drift toward boilerplate structures and conventional formats, even when your product needs something more unique. Human review ensures your documentation maintains its distinctive voice and accurately represents what makes your product different.

The over-generation tendency

AI loves to generate text. Not every docs page needs a troubleshooting section explaining how to pip install your SDK. Sometimes less is more, and humans are better at recognizing when documentation is complete versus when it’s just comprehensive.

Level up: Using system prompts for consistency

Once you’re comfortable with the basic workflow, you can take it further by setting up system prompts (also called custom instructions) that apply to every documentation task. This is particularly useful for enforcing style guides and formatting conventions without having to repeat them in every prompt.

For example, you can use system prompts to maintain consistency across your docs:

With this in place, Claude Code automatically applies these rules to every edit it makes, whether it’s fixing typos, generating FAQs, or creating new content. You can update your system prompt as your style guide evolves, ensuring all AI-generated content stays aligned with your documentation standards.

The result: less time correcting formatting inconsistencies, more time ensuring your content is actually helpful.

Editor’s note: Since Scott wrote this article, we’ve published a selection of skill files for GitBook that teach AI agents the best way to format content for GitBook compatibility. It gives your assistant a complete syntax reference for custom blocks, configuration file formats, frontmatter options, and common pitfalls — so it doesn’t just help you build your docs consistently with AI, it also improves the output.

What this means for documentation teams

This workflow represents a fundamental shift in how technical documentation gets maintained. Instead of dedicating large blocks of time to mechanical tasks like link checking, typo fixing, and consistency reviews, documentation teams can focus on higher-level work: information architecture, user research, and strategic content planning.

The AI handles the tedious work with superhuman attention to detail. The humans handle the creative work that requires judgment, taste, and product knowledge.

Getting started with an AI-first docs workflow

If you want to implement a similar system, here’s what you need:

1. GitBook with Git Sync enabled — This creates the foundation for version-controlled documentation that updates automatically.

2. Claude Code or similar agentic coding tool — You need a tool that can read and modify files based on natural language instructions.

3. A clear review process — Define what requires human review and what can be automatically merged. Start conservative and adjust as you build confidence in the system.

4. Good prompts — Start with the prompts we’ve shared here, then iterate based on your specific documentation needs.

The future of documentation work

We’re still early in figuring out how AI fits into documentation workflows. But one thing is clear: the tedious, mechanical parts of maintaining docs can increasingly be automated. That doesn’t mean documentation teams become less important — it means they can focus on the work that actually requires human judgment.

What remains is the creative work of understanding your users, structuring information effectively, and ensuring your documentation actually serves the needs of the people using your product. These are problems that require personas, user research, and strategic thinking — all areas where GitBook provides excellent tools to support your work.

The AI handles the grunt work. You handle the strategy. And together, you create documentation that’s both high-quality and maintainable.

Want to implement an AI-first documentation workflow? Sign up for GitBook and start building documentation that’s faster to maintain and easier to keep up-to-date.

Related resources

→ How to optimize your docs for AI search and LLM ingestion

→ GitBook’s Git Sync documentation

→ Build your docs around your users’ needs with documentation personas