We’ve reworked our documentation process to take advantage of AI. This includes creating four purpose-built Claude skills, one for each stage of our documentation lifecycle: analysis, design, implementation, and review. This allows us to turn around projects faster than ever while maintaining the quality our developers expect.
From spot checks to agentic action
Until recently, our use of AI in the documentation lifecycle was limited, confined mostly to the occasional sentence or paragraph rework in lieu of pulling the entire team onto a discussion call. Then the wider technology department began encouraging teams to experiment with AI to speed up work and reduce repetitive tasks.
That encouragement prompted us to investigate the agentic capability of AI, marking a shift from just talking to an LLM to having AI perform real actions on our behalf. That experimentation is what led us to AI skills, a constrained instruction set built for one task, since general AI training data doesn’t reflect Payroc’s own documentation standards for consistency, accuracy, and voice.
Four Claude skills enhancing our documentation lifecycle
Our documentation work already ran through four phases: analysis, design, implementation, and review. We didn’t ask AI to replace that process. We mirrored it, building one skill for each existing phase, finding where AI was unreliable, and keeping people at the points where judgment matters. Separate skills, rather than one covering all four, were deliberate: they let us catch a wrong turn early instead of discovering a big project had gone in the wrong direction only once it reached review.
The first version of those four skills got a piece of documentation most of the way there on its own, with writers filling in the rest, though analysis was weak and reviews were inconsistent. As we refined each of the four into a genuinely distinct skill, tuned to its own stage, that’s when we started seeing marked improvement.
The two skills that were hardest to get right
Analysis and review took the most work to get right, for different reasons.
Analysis is the first stage of our technical documentation lifecycle. It involves finding all the relevant information for a project or feature, understanding what our users are trying to achieve, and mapping out the journeys we need to document to help them get there. The Analysis skill struggled with this because it didn’t naturally anticipate the reader’s information needs, assumptions, and likely points of confusion. On a complex project, one with 10 to 12 interlinking features, it missed many of the questions and pitfalls a reader would run into.
Those details often aren’t in the main engineering ticket. They sit in the material around it, such as linked tickets, engineers’ Confluence pages, and product boards. So we fixed this by having the analysis skill work more like a writer acting as a detective. Starting from a single ticket, it now follows those links on its own, reads the supporting information, and builds a mind map of related documentation. That extra context is what lets it pick up the subtle gotchas and nuances the main ticket never mentions. Writers still read the source material themselves afterward. AI is extremely effective at discovery, but discovery and verification are different jobs.
The Review skill had the opposite problem. AI doesn’t do things in a deterministic way, so even after loading our style guide into the review skill, it applied style rules inconsistently across a full document. Our own manual review runs four passes, structural, readability, content clarity, and style guide conformance, and encoding those into a skill meant adding an open source linting tool to run rule-based checks alongside the AI’s own judgment. The principle is to use AI where judgment is required, and a linter wherever a check can be written as a rule. This means that the document being sent out for manual review with a senior member of the team is already at a high level of quality before it reaches them.
How much faster is a documentation project now?
A Support Hub rewrite from the customer service team put a real number on that improvement. We rewrote 50 articles in two weeks, at a rate of four to six each day, a project we estimate would otherwise have taken about six weeks. AI’s first pass came out very close to complete, so writers mainly checked terminology and style guide conformance instead of rewriting from scratch.
What AI now means for our published documentation
We produce documentation much faster now than we did before, but that’s only part of the story. We also now write for a second audience that doesn’t read documentation the way a person does. AI is not only an assistant for producing our documentation. A growing share of developers now also reach our documentation through an AI assistant.
We now build diagrams in Mermaid, a text-based diagram format, instead of as static images. Multimodal models can interpret images, but Mermaid exposes a diagram’s structure and relationships directly as text. Pages also carry hidden metadata meant to help point an AI agent toward the right content. Documentation intended for machine consumption benefits from explicit relationships, unambiguous terminology, and machine-readable structure, and those same characteristics tend to improve documentation for human readers too.
The new version of our docs portal goes a step further with an AI solution builder grounded in our documentation. Integrators describe what they need in plain language, and it creates a bespoke integration plan, with links to the relevant documentation and to the agentic skills our developer experience engineers build to help integrators automate parts of their own integration work. You can read more in our skills article.
Faster, but still tightly controlled
None of this is a straightforward improvement to the writing itself, and we’re careful not to present it that way. Calling AI simply “better” isn’t quite right, we still have to control quality closely; what AI actually gives us is speed. The goal hasn’t changed: accurate, clear documentation. What has changed is how quickly we can produce and maintain it. The Support Hub rewrite wasn’t a one-off. Across our Support Hub and developer portal, including documentation for new products and features, we’ve published significantly more in the last four months than in the previous four.
Getting here took real convincing, not just a tooling change. AI understandably worries people, it’s natural to fear for your job, or for your craft, when the way you’ve always worked starts changing under you. The balance of the job has shifted away from manual mapping, first-draft production, and repetitive polishing, and towards judgment, user advocacy, and quality control. AI removes mechanical work; it doesn’t remove the requirement to understand what you’re documenting. We’re quality gatekeepers, fine-tuning the AI’s work at each stage.
What doesn’t change
None of this changes who’s responsible for what we produce. Every skill in the lifecycle still ends with a person checking the AI’s work, not as a formality, but because a writer is still the one who’s actually read the source material and thought about it the way a user would. That holds whether the reader on the other end is a developer or an AI agent parsing our docs on their behalf. When an integrator points their own agent at our documentation, they are relying on a person having checked it. The documentation moves faster than it used to. What it gets checked against has not.