In the first post in this series, I described how to create an ontology that gives an agent a machine-readable model of the product. The ontology defines what exists, how the different entities relate, and which documentation pages depend on them.

In the second post, I explained how to treat page templates and prompt templates as code. These templates define what each page must contain, how it should be structured, and how the agent should use the information supplied by the ontology.

This final post focuses on the layer that connects everything: orchestration.

The ontology is the data. The templates are the contract and the strategy. The orchestrator is the control layer that decides when the system should act, what it should regenerate, and who must approve the result. Without orchestration, you have a collection of AI-enabled documentation tools. With it, you have a continuous documentation pipeline.

What is documentation orchestration?

The orchestrator is the software responsible for managing the documentation lifecycle. It detects a change in a source system, classifies that change, identifies the affected documentation, builds the context for the appropriate agent, runs the generation process, validates the output, and opens a pull request for review.

The orchestrator should not be confused with the language model. The agent generates or updates content. The orchestrator determines whether the agent should run at all and controls everything that happens before and after it. This distinction is important because most pipeline decisions should be deterministic. You should not ask a language model to guess which pages might be affected by a change when the ontology already contains an explicit dependency map. You should not ask it to choose reviewers when ownership rules can be defined in configuration. You should not ask it whether a generated page is structurally valid when a schema can provide a definitive answer.

The model handles the work that requires language. The orchestrator handles the workflow.

The scenario

I will continue with the same scenario used throughout the series:

• A mid-stage fintech company provides a payments API, a Node SDK, and a Python SDK to several thousand developers.
• Engineers merge between three and ten pull requests per day.
• The company uses a monorepo on GitHub, an OpenAPI 3.1 specification, PRDs and design specifications in Notion, and a Mintlify-hosted documentation portal.
• The documentation ontology is stored in the repository as OpenAPI extensions and catalog files.
• Page templates are implemented as typed Markdoc components.
• Prompt templates are versioned and tested alongside the page templates.

The missing component is a service that turns changes to these sources into controlled documentation updates.

For this scenario, the team creates a small TypeScript application called the documentation orchestrator. It runs through GitHub Actions and has access to the repository, the ontology index, the page and prompt templates, and the agents used to generate content.

The orchestrator has five main responsibilities:

1. Detect and classify changes.
2. Calculate their documentation impact.
3. Generate and validate the affected pages.
4. Package the changes and route them for review.
5. Publish the approved content and learn from reviewer feedback.

Detecting and classifying changes

The pipeline starts when something changes.

The most obvious trigger is a pull request that modifies an authoritative source, such as:

• The OpenAPI specification
• A catalog entry
• A public SDK interface
• A page or prompt template
• A documentation source file
• A product specification imported from Notion

A scheduled job can also run periodically to identify differences that were not introduced through the repository, such as a modified Notion page or an API specification generated by another system.

Detecting changed files is not enough. The orchestrator needs to understand what changed inside them.

Consider a pull request that modifies the OpenAPI specification. The orchestrator parses the specification before and after the change and produces a semantic diff. Instead of reporting that twelve lines changed, it reports that:

• A new optional parameter was added to POST /payment_intents/{id}/confirm.
• The parameter belongs to the checkout flow.
• Its realistic example value is missing.
• The endpoint response schema did not change.
• No existing parameter was removed or renamed.

The distinction between a text diff and a semantic diff is critical. Moving an endpoint to another location in a YAML file should not regenerate its documentation. Adding a new required parameter should.

The orchestrator stores the result in a change manifest:

change: 
	id: pr-4821 
    source: openapi 
    files: - openapi/payments.yaml 
entities: 
	- type: endpoint 
  		id: POST /payment_intents/{id}/confirm 
          changes: 
          - type: parameter-added 
            name: payment_method_options 
              required: false 
 completeness: 
 	status: blocked 
    missing: 
    	- x-example-realistic for payment_method_options

This manifest becomes the shared input for the rest of the pipeline. It also creates an early quality gate.

In this example, the pipeline does not immediately ask an agent to invent a parameter example. It reports that required source metadata is missing and blocks the documentation generation job. The source must be complete before the documentation can be trusted.

Calculating the impact of a change

Once a change has been classified, the orchestrator asks the ontology a more important question:

What documentation depends on the changed entity?

In the first post, the documentedIn relationship connected concepts, flows, webhooks, and endpoints to their documentation pages. The system can now use those relationships as a dependency graph.

For the changed confirmation endpoint, the orchestrator may find the following dependencies:

affected: 
	direct: 
	- /api/payment-intents/confirm 
transitive:
	- /guides/checkout/accept-a-payment 
    - /sdks/node/payment-intents 
    - /sdks/python/payment-intents 
    - /api/webhooks/payment-intent-processing 
generated_assets: 
	- payment-intent-state-diagram

Not every dependency necessarily requires regeneration.

The endpoint reference directly describes the new parameter, so it must be updated. The checkout guide might include a request example containing all commonly used parameters, so it is marked for evaluation. The webhook page is connected to the endpoint but unaffected by this particular change, so the orchestrator excludes it from the generation plan.

This decision should be based on explicit rules rather than an open-ended model judgment. For example:

impact_rules: 
	- change: parameter-added 
    regenerate: 
    	- endpoint-reference 
        - sdk-reference 
	evaluate: 
		- guides-containing-request-example 
- change: state-transition-added 
regenerate: 
	- endpoint-reference 
	- concept-reference 
	- state-diagram 
	- flows-containing-endpoint 
- change: endpoint-deprecated 
	regenerate: 
		- endpoint-reference 
		- guides-containing-endpoint 
		- sdk-reference 
		- migration-guide 
		- changelog

The output of this stage is a generation plan. It lists every page that will be created, regenerated, evaluated, or left unchanged, along with the reason for the decision.

That visibility matters. A reviewer should be able to see the blast radius before any documentation is modified.

Building the context bundle

For every page in the generation plan, the orchestrator builds a page-specific context bundle.

The bundle for the endpoint reference page includes:

• The relevant OpenAPI fragment
• Every ontology entry that references the endpoint
• The semantic change manifest
• The current published version of the page
• The page template and its schema version
• The appropriate prompt template
• Related examples from the Node and Python SDKs
• Recent commits affecting the endpoint
• Approved terminology and style rules

The bundle should contain only the information required for that page. Passing the entire repository to the agent makes the generation process slower, more expensive, and less predictable. It also increases the possibility that the model will use an outdated or irrelevant source.

The ontology therefore serves two purposes. It identifies which pages are affected, and it helps the orchestrator retrieve the exact context required to update each one.

The context bundle also records provenance:

provenance: 
	openapi: 
    	file: openapi/payments.yaml 
        commit: a51d97e 
        
    catalog: 
    	entries: 
        - payment-intent 
        - checkout 
        
    template: 
    	name: endpoint-reference 
        version: 3 
    prompt: 
    	name: endpoint-reference 
        version: 3.4 
    previous_page: 
    	commit: f208c31

This information travels with the generated page. A reviewer can see exactly which sources, template versions, and prompt versions produced the proposed update.

Generating and validating the documentation

The orchestrator now invokes the agent for each page in the plan.

For an existing page, the agent should not automatically rewrite the entire document. It receives the semantic change and the current page, then updates only the blocks affected by that change.

In our example, the agent adds the new payment_method_options parameter, updates the request example, and checks whether the parameter changes the explanation of what happens after the call. It does not rewrite the authentication section, introductory paragraph, error descriptions, or unrelated examples.

This reduces unnecessary differences and makes the pull request easier to review.

The generated page then passes through the validation layers defined in the second post:

1. The Markdoc compiler checks that the output conforms to the page schema.
2. The custom linter verifies documentation-specific requirements.
3. Vale checks terminology, voice, and style.
4. Code examples are tested against the sandbox API where possible.
5. Links and ontology references are resolved.
6. A change-specific validator confirms that the documented update matches the semantic diff.

If a validation error can be corrected automatically, the orchestrator retries the generation with the exact error attached.

For example:

Validation failed: 
The payment_method_options parameter is present, but its description does not explain when a developer should use it. Revise only the parameter block. Do not modify other page sections.

The number of retries should be limited. If the output still fails after the configured limit, the orchestrator stops and reports the failure. It does not continue regenerating until something happens to pass.

Repeated failure usually indicates a problem in the source context, prompt, template, or validation rule. That is a system issue that needs to be fixed upstream.

Routing documentation for human review

A page that passes automated validation is not necessarily ready to publish.

The orchestrator must decide who needs to review it. This decision depends on both ownership and risk.

Ownership comes from the ontology and repository configuration. The payment platform team owns the endpoint. The documentation team owns the page template and editorial quality. The SDK teams own language-specific examples.

Risk comes from the nature of the change.

The team defines three review levels:

Low-risk changes

These include changes such as adding an optional response field, refreshing a tested example, or correcting content to match an authoritative schema.

The documentation owner reviews the generated pull request. The relevant engineering owner is notified but is not necessarily required to approve it.

Medium-risk changes

These include new parameters, new endpoints, changed SDK behavior, and modifications to documented workflows.

Both the documentation owner and the product or engineering owner must approve the pull request.

High-risk changes

These include authentication changes, breaking changes, deprecations, billing behavior, security-related instructions, and modifications that affect legal or compliance requirements.

The pull request requires approval from the documentation owner, the relevant engineering owner, and any additional domain owner defined for that category.

The classification appears in the generation plan:

‍

review: 
	risk: medium 
    reasons: 
    	- Public API surface changed 
    	- Request example updated 
      
	required: 
    	- team: documentation 
      	- team: payments-api 
      
	optional: 
    	- team: node-sdk 
      	- team: python-sdk

The orchestrator then creates a documentation pull request containing:

• A plain-language summary of the product change
• The source pull request or commit
• The pages regenerated and the reason each one was affected
• Pages evaluated but left unchanged
• Validation results
• Source and template provenance
• The assigned reviewers
• A preview of the updated documentation

This gives reviewers more than a set of changed Markdown files. It gives them an explanation of how the pipeline reached its conclusions.

Handling conflicting or incomplete information

An agentic pipeline must also know when not to generate documentation.

Suppose the OpenAPI specification defines the new parameter as optional, but the SDK implementation requires it in one language. Or the PRD describes one behavior while the code implements another.

The agent should not decide which source is correct.

The orchestrator detects the conflict and blocks publication:

status: blocked 
conflicts: 
	- entity: payment_method_options
	sources: 
    openapi: optional
    node_sdk: required 
      
required_action:
    owner: payments-api 
    question: Is payment_method_options optional or required?

Once the source owners resolve the inconsistency, the pipeline runs again using the corrected sources.

This is an important boundary. The goal of an agentic pipeline is not to make documentation appear complete when the product knowledge is incomplete. Its job is to expose missing knowledge early and direct it to the person who can resolve it.

Publishing the approved update

Once all required reviewers approve the pull request, the documentation changes are merged.

The normal documentation build publishes the pages to a preview or production environment, depending on the team’s release policy. The orchestrator then records the relationship between:

• The product change
• The generation plan
• The generated pages
• The reviewers and approvals
• The deployed documentation version

This creates an auditable history. If an incorrect update reaches production, the team can identify not only who approved it, but also which source data, prompt, template, and agent run produced it.

The pipeline can also coordinate documentation publication with the product release.

A new endpoint may be merged into the codebase before it is publicly available. Its documentation can be generated and approved immediately but held behind a release condition. When the feature flag or release version becomes active, the approved documentation is published without requiring another writing cycle.

Closing the feedback loop

Publishing the page is not the end of the pipeline. The final responsibility of the orchestrator is to learn from the review process.

Reviewer corrections should be classified according to the layer that caused the problem:

• Source correction: The OpenAPI specification, SDK annotation, or catalog entry was incomplete or wrong.
• Ontology correction: A relationship or dependency was missing.
• Template correction: The page structure did not provide a place for required information.
• Prompt correction: The agent received the right information but used it incorrectly.
• Validation correction: The output problem should have been caught automatically.
• Page-specific correction: The issue applies only to this particular page.

This classification prevents the team from repeatedly correcting the generated output without fixing the system that produced it.

If reviewers repeatedly add the same explanation to every new endpoint page, that explanation belongs in the template or prompt. If the orchestrator repeatedly misses a guide affected by an API change, the ontology is missing a relationship. If agents produce invalid examples, the source needs stronger example metadata or the pipeline needs executable example tests.

The most valuable output of human review is not the corrected sentence. It is the rule that prevents the same correction from being necessary again.

Measuring whether the pipeline works

A continuous documentation pipeline should be measured as a system.

Useful indicators include:

• Time between a product change and the creation of its documentation pull request
• Percentage of product changes correctly matched to affected pages
• Percentage of generated pages approved without content corrections
• Validation failures grouped by template, prompt, and rule
• Recurring reviewer corrections
• Documentation changes blocked by incomplete or conflicting source information
• Product changes merged without an associated documentation decision

The goal is not to maximize the amount of text generated without human involvement. A pipeline that produces large amounts of plausible but unreliable documentation is not successful.

The goal is to make documentation updates timely, traceable, consistent, and proportionate to the product change that caused them.

The complete agentic documentation pipeline

The three layers described in this series now form a complete system.

1. The ontology defines what the product contains and how its entities connect.
2. The templates define how each type of documentation should be structured and how the agent should transform product knowledge into content.
3. The orchestrator detects changes, calculates their impact, manages generation and validation, routes the output to the right reviewers, and controls publication.

The orchestrator detects changes, calculates their impact, manages generation and validation, routes the output to the right reviewers, and controls publication. Together, these layers change documentation from a collection of manually maintained pages into a governed product system.

This does not eliminate the technical writer. It moves the writer’s judgment upstream. The writer decides which product relationships must be modelled, what complete documentation looks like, which changes require human review, what quality rules should block publication, and how feedback should improve the system. In a traditional documentation workflow, that judgment is applied one page at a time. In an agentic pipeline, it is encoded into the architecture and applied continuously across the entire documentation set.

That is the larger shift behind this series.

The future of technical writing is not simply using AI to write faster. It is designing systems that know what to document, how to document it, when the documentation must change, and when a human needs to make the final decision.

‍