I've lived that cycle as a technical writer for years. So I built something to fix it.

This is the story of contentGen — a custom AI agent I built inside VS Code that reads a Jira ticket, studies the Figma design, cross-references Confluence, checks the existing documentation codebase, and then writes a finished, convention-compliant help topic. What used to consume the better part of a working day now takes under 30 minutes. This article is about how it works, what it took to build it, and why I think VS Code agents are one of the most underestimated tools in the industry right now.

1. The Problem Nobody Talks About in Tech Docs​

Let's paint the picture honestly.

When a new feature ships, a technical writer typically needs to:

• Find and read the Jira ticket (and its child tickets, and its linked tickets)
• Track down the Confluence page where someone wrote a discovery brief three sprints ago
• Open the Figma design file and navigate to the right screens, which may have been reorganized since the last time you looked
• Cross-check whether existing documentation already covers part of this feature
• Understand the naming conventions, the product terminology, the UI labels that are actually shipping
• Figure out which folder in a documentation codebase this content belongs in
• Write a first draft that matches the established writing style, structure, and formatting conventions
• Review it against style guides, snippet libraries, and localization constraints

That's not a writing task. That's a research project that happens to end in writing. And the research phase alone — before a single word of documentation is typed — routinely takes five to six hours for a single medium-complexity feature.

Now multiply that across a fast-moving product team with multiple concurrent releases, and you start to understand why documentation debt compounds so quickly.

The bottleneck isn't skill. It's context-gathering. And context-gathering is exactly what AI is good at.

2. What Is a VS Code Agent — And Why Most People Underestimate Them​

Most people who've used GitHub Copilot think of it as an autocomplete engine that got smarter. A helpful pair programmer. A fast way to generate boilerplate. That's a reasonable impression if you've only used the chat panel.

But VS Code Copilot agents are something different in kind, not just degree.

An agent in VS Code isn't just a chatbot with context about your file. It's a configurable, tool-wielding, goal-oriented workflow runner. You define it in a plain Markdown file with a YAML header. You give it a description, a list of tools it's allowed to use, a set of skills it can load, behavioral guardrails, a decision workflow, and a clear understanding of what it's supposed to do — and what it must never do.

When invoked, the agent can:

• Read and write files in your repository
• Execute search queries across your codebase
• Call external APIs and MCP (Model Context Protocol) servers — including Jira, Confluence, Figma, and GitHub
• Ask clarifying questions using structured question cards
• Load modular "skill" definitions to apply specialized domain knowledge
• Hold itself to a strict confirmation gate before making changes

The key insight that most developers and writers miss is this: VS Code agents aren't assistants that respond to prompts. They are autonomous actors that execute workflows. The difference matters enormously once you start building with them.

3. Meet contentGen: My Documentation Agent​

contentGen is a custom VS Code agent I designed and built from scratch. The elevator pitch is simple:

Give it a Jira ticket number. It reads the design, checks the documentation codebase, and produces a finished, ready-to-review help topic in the correct file, in the correct folder, following the correct conventions.

But the real value isn't the output — it's what happens between the input and the output. contentGen doesn't generate documentation by guessing. It researches first, synthesizes what it finds, and only writes once it understands the feature as well as a writer who has spent half a day on it.

It sits inside the documentation repository as a single .agent.md configuration file. When a writer — or a PM, or an engineer who wants to contribute — invokes it from VS Code, it takes over the research and context-gathering phase entirely, leaving the writer to review and refine rather than discover and draft.

The agent is purpose-built for a MadCap Flare documentation environment, integrated with Atlassian's Jira and Confluence, connected to Figma, and wired into the GitHub repository. It knows the project's folder structure, writing conventions, snippet libraries, template patterns, and localization constraints. It doesn't just write documentation. It writes this team's documentation.

4. How It Actually Works: The Research-Then-Write Pipeline​

The core design principle of contentGen is research before writing. The agent will not touch a source file until it has built a complete picture of what it's creating.

Here's the pipeline in plain English:

Step 1 — Understand the request. The agent begins by asking the writer a structured set of questions using an interactive question card: Is this a new topic, a revision, or release notes? Which app or product does it belong to? Is there a Jira ticket, a Figma link, or a known file path? It collects only what it needs and recovers missing context through research when possible.

Step 2 — Jira first. The agent pulls the ticket, reads the description, acceptance criteria, and linked sub-tasks. It follows links to related engineering tickets or discovery briefs to understand not just what the feature does, but why it exists and who it affects.

Step 3 — Figma as the source of truth for UI. The agent opens the linked Figma design and reads it — literally capturing the actual UI labels, button names, field titles, workflow states, and task sequences from the designed interface. This is critical. Documentation that's written from a ticket description and not the design frequently uses wrong labels, wrong names, and wrong sequences. Figma eliminates that.

Step 4 — Confluence for context. Any Confluence pages linked to the ticket — discovery briefs, rollout notes, business rules, permissions documentation — are read and synthesized. Edge cases, caveats, and non-obvious behaviors that never make it into a ticket description often live here.

Step 5 — Repo search for existing coverage. Before creating anything new, the agent searches the documentation codebase for existing topics, snippets, variables, and templates that relate to the feature. It checks whether the content already exists, whether it needs extending, and whether there are established patterns from similar features it should follow.

Step 6 — Propose before writing. The agent presents a high-level summary of its findings: the proposed file path, the sections it plans to create, the template it will use, any variables or snippets it plans to reference. The writer reviews this plan and confirms before a single source file is touched. This gate is non-negotiable — the agent cannot proceed without approval.

Step 7 — Write with conventions loaded. Only after confirmation does the agent write the source file. As it does, it loads its specialized skills to apply the correct HTML structure, UI formatting rules, and localization constraints. The output lands in the right en-us folder, in the right format, ready for review.

Step 8 — Validate. The agent checks its output against repo conventions and obvious structural issues before reporting completion.

The total time for this pipeline, from invocation to a ready-to-review draft: under 30 minutes. The equivalent manual process averaged five to six hours.

5. The Skills Architecture: Modular Intelligence​

One of the most important design decisions I made while building contentGen was separating its domain knowledge into modular "skill" files rather than baking everything into the agent definition.

A skill in this system is a standalone Markdown file — a SKILL.md — that contains deep, tested, task-specific instructions. The agent loads skills dynamically using the read_file tool at the moment they're needed. It doesn't carry all knowledge all the time. It reaches for the right expertise at the right step.

contentGen uses five skills:

• determine-content-scope — Helps the agent interview the user effectively to understand the task type, delivery scope, and app location without over-asking or under-asking.
• interactive-question-ux — Governs how the agent asks questions: structured cards, clear options, no unnecessary prompts.
• apply-flare-conventions — The deep rulebook for MadCap Flare file structure, topic anatomy, TOC integration, and snippet usage.
• format-ui-elements — Handles correct formatting of buttons, menus, fields, paths, and UI labels in the HTML source.
• multilingual-guardrails — Ensures the agent only writes in the correct locale folders and never accidentally touches translated content.

This modular approach does something subtle but powerful: it makes the agent maintainable. If the style guide changes, you update one skill file. If the localization rules get more complex, you update one skill file. The agent itself stays stable. The knowledge it applies evolves independently.

It also makes the system extensible. Want to add support for a new documentation product? Create a new skills file that describes its conventions. The agent picks it up automatically.

6. Built-In Guardrails: This Agent Asks Before It Acts​

I want to spend a moment on something that I think separates a well-engineered AI agent from an impressive demo: intentional restraint.

contentGen has explicit boundaries encoded into its definition. These aren't afterthoughts — they are first-class design requirements.

It will not invent product behavior. If Jira, Figma, Confluence, and the existing codebase don't contain enough information to accurately describe a feature, the agent stops and asks. It will not fill gaps with plausible-sounding fabrications, because in documentation, a plausible-sounding wrong answer creates real user confusion.

It will not write without confirmation. The proposal-then-confirm gate before writing source files isn't optional. Every invocation requires a human to review the plan and approve it. This keeps the writer in the loop without requiring them to do the research.

It will not wander out of scope. The agent changes only the files required by the user's request. If it notices something unrelated that looks inconsistent or outdated in a nearby file, it does not fix it. Scope creep in an automated writing agent produces hard-to-review diffs and unpredictable results.

It will not touch non-English content. The multilingual guardrail enforces a hard boundary: contentGen works exclusively in the en-us source folders. Translated content is produced through a separate localization pipeline and must never be overwritten by an agent operating on English source.

It stops and asks when uncertain. If the correct app folder can't be verified from context, it asks. If a variable name is ambiguous, it asks. If the ticket doesn't have enough detail to determine which existing topic should be revised, it asks. A concise, targeted question is always preferable to a confident wrong answer.

These guardrails are what make the agent trustworthy enough to run on a production documentation codebase. Impressive output from an AI that can't be trusted is a liability, not an asset.

7. What It Took to Build It: Design Decisions and Non-Obvious Challenges​

Building contentGen from scratch taught me things about AI agents that I didn't find in any tutorial.

The .agent.md format is deceptively powerful. The file format is simple YAML frontmatter plus Markdown. But the depth of behavioral instruction you can encode in that Markdown — the workflow steps, the decision logic, the tool usage patterns, the explicit boundaries — is substantial. The skill is not in learning the syntax. It's in knowing what to write.

MCP server integration is where the real power lives. Connecting the agent to Atlassian's MCP server, Figma's MCP server, and GitHub's MCP server transformed it from a smart file editor into a genuine research agent. These integrations let it reach out to the actual systems of record — not cached summaries, not hallucinated approximations — and pull real, current information. Getting these configured correctly required understanding how MCP servers expose their tools and how to reference them in the agent's tool list.

Telling the agent where things live is the hardest part. The most brittle aspect of any documentation agent is the folder-mapping problem: given a feature description, determining which of a dozen possible en-us product folders the content belongs in. I solved this partly through the determine-content-scope skill, partly through the repo instructions that map product names to folder paths, and partly by instructing the agent to ask when the evidence is ambiguous rather than guess. Getting that triangulation right took more iteration than any other aspect of the build.

Skills files need to be tested like code. Early versions of the skills definitions produced inconsistent results because they were too abstract. The skill files that work well are the ones that contain concrete, specific, tested instructions — the same level of precision you'd want in a unit test. Vague guidance produces vague output.

The confirmation gate changed how I thought about the agent. Originally, I built the confirmation step as a safety feature. Over time I came to see it differently: it's a communication protocol between the agent and the writer. The proposal summary the agent produces before writing is itself valuable — it forces the agent to articulate its reasoning and gives the writer a fast way to spot misunderstandings before they become wrong files.

8. Real-World Impact: Before and After​

Let me give you the honest comparison.

Before contentGen, the research phase of a documentation task looked like this: open Jira and spend 20-30 minutes reading the ticket and all its linked context. Search for the Confluence page (which might be linked from the ticket, might not be). Open Figma and navigate to the right frame, re-learning the design tooling every time it gets updated. Search the documentation codebase for related topics. Find the right template. Read the style guide to confirm the right formatting for the feature type. All of that before writing the first sentence. Minimum time: five to six hours for a moderately complex feature. Sometimes a full day.

After contentGen, the writer provides the Jira ticket number and answers a four-question card. The agent reads everything, synthesizes it, and presents a complete content plan in one step. The writer reviews and approves it. The agent writes the draft. Total elapsed time: under 30 minutes.

The quality difference matters too. Manually researched documentation is only as good as what the writer happened to find and prioritize. contentGen reads all of it — every linked ticket, every Confluence note, every Figma annotation — and incorporates it. The drafts it produces are more complete on first pass precisely because the research is more thorough than any human would do under deadline pressure.

This isn't about replacing writers. The writer's review and refinement step is still essential, and the agent is built to require it. What's been eliminated is the grinding, low-creativity, high-effort research that precedes real writing — the part that consumes time without producing insight.

9. What This Tells Us About the Future of Docs — and AI Agents​

I built contentGen to solve a problem I had today. But what it implies about the near future of technical communication is worth sitting with.

The documentation workflow I described in section one — research, synthesize, locate, draft, format, validate — is fundamentally a workflow that requires navigating multiple systems, applying many different rule sets, and producing a structured output in a constrained format. That is exactly the class of problem that well-designed AI agents handle well.

What we're beginning to see is a bifurcation in how AI gets used in knowledge work. On one side, there's AI-assisted work: a writer uses AI to go faster on tasks they're already doing. On the other side, there's AI-delegated work: a writer defines a workflow precisely enough that an agent can execute it end-to-end, and the writer's role becomes oversight, review, and direction.

contentGen lives on the second side of that line. And the gap between the two is not technical capability — it's workflow design. The teams that will lead in AI-assisted documentation aren't the ones with the best prompts. They're the ones who invest in encoding their workflows precisely enough that agents can run them reliably.

VS Code agents — and the MCP protocol that wires them to real data systems — represent a platform that most of the industry hasn't fully absorbed yet. The tools are here. The integration points are here. The gap is in knowing how to design for them.

If you're a technical writer, a docs engineer, or a PM who owns documentation quality and you're not experimenting with agents built on this platform, this is the moment to start.

10. What's Next for contentGen​

contentGen is working in production, but the backlog of ideas for what it could do next is longer than when I started.

At the top of the list: release notes automation. The agent already supports drafting release notes as a task type, but I want to develop a dedicated workflow that can produce a complete, multi-feature release note document from a sprint's worth of Jira tickets in a single invocation.

I'm also exploring revision detection — giving the agent the ability to monitor a watched set of Jira tickets and proactively flag when documentation it previously generated may be outdated based on changes to the linked design or ticket status.

Longer term, I want to extend the skills architecture to support multiple documentation products more dynamically, allowing a single agent invocation to coordinate changes across related help systems when a shared feature spans multiple products.

There's also the question that every tool builder eventually confronts: should I share it? The core agent pattern is generic enough to be useful outside this specific codebase. I'm thinking through what a generalized version of contentGen would look like — one that could be seeded with a team's own style guide, folder conventions, and tool connections.

If you're working on something similar, or thinking about how to bring this kind of workflow automation to your documentation team — I'd genuinely like to compare notes. Find me on LinkedIn.

Why Cloud Docs Fail​

Most cloud documentation failures come from the same three root causes:

1. Docs are written once, never updated. Cloud products ship constantly. Docs tied to a single release cycle fall out of date in weeks.
2. Architecture lives only in engineers' heads. Concepts like tenancy, region routing, or identity federation are never properly explained because everyone on the team assumes the reader already knows.
3. No clear audience separation. A single doc trying to serve a DevOps engineer, a security administrator, and an end user will serve none of them well.

The Docs-as-Code Foundation​

The single highest-ROI investment for any cloud documentation team is treating docs like code. That means:

• Version control everything. Every doc change is a commit, reviewable and reversible.
• Docs live next to the product. When an engineer merges a feature, the doc update is part of the same PR.
• CI/CD validates your docs. Broken links, missing screenshots, and outdated API parameters get caught before they reach users.

At Diligent, moving to a docs-as-code workflow reduced our time-to-publish from days to hours and cut stale-doc reports by over 60%.

Structure for Cloud Concepts​

Cloud products have unique structural needs. Here's a framework that works:

Conceptual Foundation First​

Before any how-to, ensure your readers understand:

• What the product is (one sentence, no jargon)
• What problem it solves (use a real customer scenario)
• How it fits into their existing stack (a simple architecture diagram does more than three paragraphs)

Task-Oriented Procedures​

Users come to docs to accomplish something. Structure every procedure around a job-to-be-done:

Before you begin
  Prerequisites (access, roles, dependencies)

Steps
  1. ...
  2. ...

Result / What happens next

Reference as a Separate Layer​

API references, configuration parameters, and error codes belong in their own section. Don't bury them inside procedures — engineers will find them via search, not by reading linearly.

AI-Augmented Documentation Workflows​

In 2025, the teams winning at cloud documentation are using AI as a force multiplier, not a replacement. My current workflow:

1. AI drafts the skeleton from an OpenAPI spec or Jira ticket
2. I add judgment — use cases, caveats, the "why behind the what"
3. SME review catches technical inaccuracies
4. AI checks for consistency, terminology drift, and broken links post-review

The key insight: AI is excellent at structure and completeness; humans are essential for accuracy and context.

Metrics That Actually Matter​

Stop measuring documentation by page count. Measure:

• Support ticket deflection rate — are users self-serving?
• Time-on-page for critical procedures — are they reading, or bouncing?
• Search-exit rate — are users finding what they searched for?
• API onboarding time — how long until a developer's first successful API call?

Closing Thoughts​

The best cloud documentation is invisible — users find what they need, do what they came to do, and move on. That only happens when docs are treated as a product, not an afterthought.

Start with docs-as-code, build a strong conceptual layer, use AI to scale, and measure outcomes over output.

Questions or war stories? Find me on LinkedIn.

The Developer's First Question​

When a developer lands on your API documentation, they have one question before any other: "Can this API do what I need in the time I have?"

That question needs to be answered within 90 seconds. If it isn't, they leave.

Everything about good API documentation design flows from this constraint.

The Three Layers of API Docs​

Great API documentation works at three distinct levels simultaneously:

1. The Quickstart (0–10 minutes)​

A single, complete, copy-paste-runnable example that produces a real, meaningful result. Not "Hello World" — something that demonstrates the actual value of the API. At Diligent, our best-performing quickstarts showed a governance workflow completed end-to-end, not just an authentication handshake.

2. The Concept Guide (10–30 minutes)​

Explains the mental model. What is an "entity" in your system? How does authentication work? What are rate limits and how do they apply to this specific API? Developers who skip the concept guide write fragile integrations that break in production.

3. The Reference (always)​

Complete, exhaustive, accurate. Every parameter, every response code, every error message. Auto-generated from your OpenAPI spec — but always human-reviewed. Auto-generation handles completeness; humans handle clarity.

What Makes a Reference Actually Useful​

The worst API references are technically complete but practically useless. Here's the difference:

Bad parameter description:

include_archived — boolean. Whether to include archived items.

Good parameter description:

include_archived — boolean, default: false. When true, the response includes items with status archived. Use this when building audit reports or data exports. Omit for standard product workflows where archived items should be hidden.

The good version adds: the default, the context for when to use it, and when to leave it out. It takes 30 more seconds to write and saves developers hours of debugging.

Error Messages Are Documentation​

Every error response your API returns is documentation your developers will read at 2am when something is broken. Write them accordingly.

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "The authenticated user does not have the 'admin.users.read' permission required for this endpoint.",
    "details": {
      "required_permission": "admin.users.read",
      "documentation": "https://docs.example.com/permissions#admin-users-read"
    }
  }
}

Not:

{
  "error": "403 Forbidden"
}

Interactive Examples Are Non-Negotiable​

In 2025, static code snippets are table stakes. Developers expect to run examples directly in the docs. Tools like Scalar, Redoc, or Swagger UI with real sandboxed credentials remove friction from the "first successful call" moment, which is the most critical milestone in developer onboarding.

The Changelog Is Part of the Docs​

API consumers need to know when things change. A well-maintained changelog:

• Lists every breaking change with a migration guide
• Notes deprecations with a sunset date (minimum 6 months notice)
• Calls out performance improvements or new capabilities

Treat the API changelog as a product, not an administrative chore.

Measuring API Documentation Success​

The metric I care about most: time to first successful API call for a new developer. Track it. If it's over 30 minutes, something is wrong. If it's over an hour, your docs are actively costing you integrations.

Other useful signals:

• GitHub issues or Stack Overflow questions citing your docs
• Support tickets that start with "I read the docs but..."
• Direct developer feedback in post-integration surveys

Final Thought​

Developers are your most skeptical readers. They don't trust what they can't verify. Every claim in your API docs should be provable with a runnable example. When in doubt: show, don't tell.

Why Collaboration Is a Technical Skill​

Most technical writers get trained on tools and style guides. Few get trained on how to extract information from a senior engineer who has three minutes between meetings, or how to get a PM to prioritize documentation in a sprint that's already overloaded.

These are learnable skills, and they matter as much as your ability to write a clean procedure.

Working With Engineers​

Engineers are your most valuable source of technical truth. They are also, frequently, your most time-constrained stakeholders.

What works:

• Async-first. Never ask for a meeting when a Slack thread or a commented PR would work. Engineers prefer async; it respects their flow state.
• Specific questions. "Can you explain how the authentication works?" gets a 20-minute explanation. "In the auth flow, does the refresh token expire if the access token is never used?" gets a two-sentence answer you can write directly into docs.
• Review, don't approve. Send engineers a draft and ask them to flag anything factually wrong. Don't ask them to write — they will hate it. Do ask them to correct — they will care about accuracy.
• Embed in sprints. Attend standups. Read Jira tickets. You'll learn things nobody thought to tell you.

Working With Product Managers​

PMs control the roadmap and, often, the documentation budget indirectly. They're also the best source for the "why" behind features — context that makes the difference between a procedure and an explanation.

What works:

• Ask about the user problem, not the feature. "What problem does this solve for the user?" produces better documentation material than "What does this feature do?"
• Negotiate doc scope early. Documentation scope should be in the definition of done. If it's not, advocate for it at sprint planning, not retrospective.
• Provide metrics. PMs respond to data. If your knowledge base reduced support tickets by 30%, that's the language that earns documentation a seat at the table.
• Flag documentation risk. If a feature is shipping without adequate docs, that's a business risk. Name it clearly: "Shipping X without documentation means support ticket volume for this workflow will increase."

Working With Designers​

The best time to collaborate with a designer is before the UI is finalized, not after. UX writing — error messages, tooltips, onboarding flows — is documentation that lives in the product.

What works:

• Join design reviews. Figma comments from the documentation perspective catch issues ("This error message doesn't tell the user what to do next") before they're coded.
• Maintain a content inventory. Keep a shared doc of all UI strings that need copy. Designers can't write everything; having a designated owner prevents omissions.
• Align on terminology early. If the product calls it a "workspace" and docs call it a "project," users get confused. Terminology alignment is a joint responsibility.

The Information Architecture Problem​

The hardest cross-functional challenge in technical writing is information architecture: deciding what lives where, who owns what, and how content stays consistent across docs, UI, and support.

My approach:

1. Establish a single source of truth. Pick one place (Confluence, Notion, a GitHub repo) where canonical product definitions live.
2. Make it everyone's job to update it. Not just the writer's. When a PM changes a feature name, they update the glossary.
3. Review it quarterly. Entropy is constant. Content rots. Schedule time to audit.

When Collaboration Breaks Down​

Sometimes stakeholders don't engage, reviews get skipped, and docs ship with known errors. This happens. What matters is how you respond:

• Document the gap. File a ticket, send a Slack message with a timestamp. Create a record.
• Quantify the impact. "We shipped without documenting the new permission model. Support has logged 14 tickets in 48 hours" is more actionable than "we need better process."
• Propose the fix, not just the problem. Come with a solution: a 30-minute doc sprint, a dedicated review slot, a definition-of-done update.

Building Long-Term Trust​

Every accurate doc you ship builds trust with engineering. Every support ticket you deflect builds trust with product. Every clear error message builds trust with design. These compound over time.

The technical writer who is embedded, collaborative, and data-driven eventually becomes the person the team considers before shipping, not after.

That's the goal.