Documentation Automation Platform
Completed Jira tickets trigger AI documentation updates in GitHub, reviewed through Quill and synced to Zendesk after the pull request merges.
- sequential context steps required before any drafting begins
- 4sequential context steps required before any drafting begins
- codebase searches mandated per article to confirm exact product terminology
- 2+codebase searches mandated per article to confirm exact product terminology
- repositories scanned for changes feeding the refresh queue
- 6repositories scanned for changes feeding the refresh queue
- queue item processed at a time, trading throughput for correctness
- 1queue item processed at a time, trading throughput for correctness
I built AI documentation automation that starts when a Jira ticket is completed. An agent gathers ticket and codebase context, creates or updates documentation in GitHub, and opens a pull request. The documentation team reviews and edits the proposed changes through Quill, the workflow's Electron/React/TypeScript review app. Once the PR merges, the documentation is synced to Zendesk. Context enrichment and a blocking clarification gate keep the agent from drafting through unresolved gaps.
The problem
The first version drafted from a ticket description alone — typically a one-line summary written for a project manager, not an engineer. It did not reliably read the linked engineering tickets, never searched the codebase to confirm what things were actually called, and never surfaced an ambiguity. The output was plausible and imprecise: approximate UI labels, missed edge cases, and multiple revision rounds per article. The agent was not short of capability; it was short of context, and it had no way to say so.
Constraints
- The ticket description cannot be trusted as the specification — it is written for a different audience than the documentation.
- Published articles are customer-facing, so an approximate field name is a defect, not a rough edge.
- Related engineering tickets are often not formally linked, so discovery cannot rely on link graphs alone.
- Generated documentation must be reviewed through Quill before the GitHub PR merges; Zendesk receives the merged documentation.
Architecture
Decisions
What I chose, why, and what I turned down to get there.
A clarification gate that blocks drafting
The agent compiles a numbered list of what it cannot resolve from the available evidence and waits for answers before writing a word. This is the single most valuable behaviour in the pipeline: the failure mode of a documentation agent is not refusing to write, it is writing confidently from a gap. Making the gap explicit converts a silent assumption into a question someone can answer in seconds.
Considered and rejected
- Letting the agent proceed on best-effort assumptions — faster per run, and the source of every revision round it was meant to eliminate
Mandate codebase search before drafting, not as a fallback
At least two searches per article, one broad on the feature and one narrow on a specific component or configuration key. Documentation has to use the product's exact terminology, and the only authoritative source for what a field is called is the code that names it. Tickets describe intent; the codebase describes what shipped.
Search for related tickets rather than trusting links
A bounded keyword search over recently-tested tickets discovers work that is relevant but was never formally linked, deduplicated against what the link graph already returned. Bounding it by recency and status keeps the context pool relevant instead of merely large — an unbounded search would trade one context problem for another.
Distil the writing rules from published work
Rather than hand-authoring a style guide, the rules were derived from the last several published release notes — how entries open, the tone and sentence length, the recurring constructions. Critically, patterns that violated the existing rules were noted and deliberately not encoded, so the result matches the house voice without inheriting its bad habits. Style guidance written from scratch drifts from the real corpus; this cannot.
Considered and rejected
- Hand-written tone guidance — already existed, and was what the output was drifting from
Validate formatting in the workflow, not only in the prompt
A malformed comment format persisted after the prompt was corrected, so a validation and correction layer went into the workflow node itself. When a model is the only thing enforcing a structural contract, that contract is advisory. Defense in depth is cheaper than a class of formatting bugs that reappear whenever the prompt changes.
From completed ticket to published documentation
A Jira ticket reaching Done automatically triggers the documentation agent. The agent gathers the relevant context, creates a new article or updates an existing one in the GitHub documentation repository, and opens a pull request. Reviewers use Quill to inspect the rendered changes, edit the draft, and approve the PR. After the PR merges, the synchronization workflow updates Zendesk with the merged documentation.
- Jira completion starts the authoring workflow; it does not publish an article by itself.
- Quill is the human review application within this automation, with GitHub retaining the proposed changes and approval history.
- Zendesk synchronization follows the documentation PR merge, so customers receive the reviewed version.
Keeping the scheduled refresh bounded
Alongside the Jira-triggered workflow, a collector scans merged code pull requests across six repositories, extracts which product areas changed, and maintains a queue with per-item state — first seen, last seen, last run, retry count. A scheduled runner then processes that queue rather than regenerating everything. These code changes feed documentation refresh; merging the resulting documentation PR is the separate step that leads to Zendesk synchronization.
- The queue is processed one item at a time, sequentially, on purpose: parallel runs collided over shared template files. Throughput was the correct thing to trade for correctness here, because the deadline is weekly.
- Item names are canonicalized and deduplicated, so repeated pull requests touching the same area update one queue row instead of creating several.
- Retries and failure handling live in the queue rather than in the agent, so a transient failure does not lose the work.
Quill provides the human review step
Quill makes the agent's GitHub PRs reviewable by the documentation team. Its WYSIWYG editor, rendered comparisons, embedded agent terminal and per-branch Git worktrees let reviewers inspect and correct a proposal before approving it. Quill is the review component of this documentation automation; the surrounding workflow triggers authoring and syncs merged changes to Zendesk.
Stack
- n8n
- Model Context Protocol
- Python
- CLI agents
- Jira
- Quill
- TypeScript
- React
- Electron
- Confluence
- Zendesk
- GitHub
- AWS Bedrock
What was mine
Built the documentation automation, including the Jira-triggered agent workflow, context enrichment, refresh queue, GitHub PR delivery, Quill review app and synchronization of merged documentation to Zendesk. The work grew from an epic opened by engineering leadership. The documentation team owns editorial decisions and approval before publication.