# Markdown simplicity, DITA rigor: bringing AI into documentation validation

Markdown is much simpler than XML-based formats such as DITA and doesn’t require expensive tooling to present users with nicely laid-out documentation. So, this might look like the way to go for any company eager to minimize documentation production costs and avoid vendor lock-in.

However, as far as documentation is concerned, a fine layout isn’t enough. Users must be able to browse consistently structured content to quickly find the type of information they’re looking for. That’s where DITA and its well-defined DTDs help: they provide a predictable structure that lets users quickly find actionable conceptual information, procedures, or reference material. Writers, for their part, first select the type of topic they want to create and are then prevented from producing ill-structured content.

Linters are great at detecting and preventing syntax inconsistencies, but they won’t stop technical writers from mixing multiple information types in the same topic, which can frustrate users.

Deterministic linters such as markdownlint and Vale can ensure that basic formatting and stylistic rules are applied. AI-based checkers could assess whether topics comply with specific information types, although their interpretation would be probabilistic. Markdown would keep its authoring simplicity, while AI-assisted semantic analysis and deterministic validation would bring in some of the structural discipline traditionally associated with DITA, though not DITA’s authoring-time guarantees.

## Example: mixing up tasks, concepts, and reference material

Let’s suppose you create this ill-typed topic, mixing several types of information.

```markdown
# Configure a static IP address

Assign a fixed IPv4 address to a server so that other hosts can always reach
it at the same address.

## How Netplan works

Netplan doesn't configure network interfaces itself. It reads the YAML files in
`/etc/netplan/` and generates configuration for a back-end renderer, either
`systemd-networkd` or `NetworkManager`. This is why a mistake in a YAML file
can leave a server unreachable after the next reboot.

1. Open `/etc/netplan/01-netcfg.yaml` in your editor of choice.
2. Set `dhcp4` to `false`.
3. Add static settings:

   ~~~yaml
   network:
     version: 2
     ethernets:
       eth0:
         dhcp4: false
         addresses: [192.0.2.10/24]
         routes:
           - to: default
             via: 192.0.2.1
         nameservers:
           addresses: [192.0.2.53]
   ~~~

   | Key           | Accepted values       | Notes                    |
   |---------------|-----------------------|--------------------------|
   | `dhcp4`       | `true`, `false`       | Defaults to `false`.     |
   | `addresses`   | List of CIDR prefixes | Required for static IPs. |
   | `routes`      | List of `to`/`via`    | Replaces `gateway4`.     |
   | `nameservers` | `addresses`, `search` | Optional.                |

   If `dhcp4` stays `true`, the interface gets both a leased address and the
   static one, which makes routing harder to predict.

4. Run `sudo netplan try`.

   `netplan try` applies the configuration and reverts it after 120 seconds
   unless you confirm it.

5. Press Enter to keep the new configuration.
```

markdownlint’s default rules report no issues. Neither does Vale, depending on how you configured it. Yet a reader who wants to set up a static address must get past an architecture explanation and a parameter reference table before reaching the procedure they’re looking for. On the other hand, a reader only interested in detailed routes parameters must know they’re buried in a task, after some conceptual information.

### AI semantic analysis

A Markdown parser sees a heading, a paragraph, and a list and doesn’t raise any alarm. A style linter checks the prose's conformance to the corporate style guide and gives a green light.

Don’t leave it to users to catch this kind of error: a language model can help assess whether the information type is consistent before users are presented with unstructured content they will struggle to use effectively.

Asked to classify each chunk of content and cite its source lines, an LLM might return:

```yaml
dominant_purpose: procedure   # task title, imperative numbered steps
passages:
  - { lines: 3-4,   type: goal,      confidence: high }
  - { lines: 6-11,  type: concept,   confidence: high, about: renderer model }
  - { lines: 13-46, type: steps,     confidence: high, steps: [13, 14, 15, 41, 46] }
  - { lines: 17-29, type: example,   confidence: high, parent: step 3 }
  - { lines: 31-36, type: reference, confidence: high,
      parameters: [dhcp4, addresses, routes, nameservers] }
  - { lines: 38-39, type: concept,   confidence: medium, about: dhcp4 }
  - { lines: 43-44, type: concept,   confidence: low, alternative: step result }
```

As the confidence levels imply, we don’t get clear-cut answers as we would with a DTD. But running these automated tests in the CI pipeline could be inexpensive. And nothing prevents us from leveraging LLMs to propose further evaluations beyond what a classical DTD does, provided we treat the model’s answers as candidates rather than verdicts.

### The candidate structure

The model then proposes a graph of what each passage does for the reader. The heading hierarchy, by contrast, would make How Netplan works the parent of the steps:

<Diagram
  title="Candidate structure extracted from a mixed task topic"
  caption="Candidate structure extracted from the Netplan topic. The goal and five steps form a valid sequence. A topic-level concept and a reference table of four parameters embedded in step 3 are flagged by the task contract, and the passage under step 4 has an uncertain classification that needs human review."
  description="A three-column graph. Center column: a task goal, Static IP address, followed by five ordered steps: Open YAML file, Disable DHCP, Add static settings, Run netplan try, and Confirm. Left column: three concepts. Renderer model precedes the task goal and is flagged. DHCP plus static is a note attached to step 3 and explains the dhcp4 key. Rollback timer is a note attached to step 4, with an uncertain classification. Right column: a reference table, Interface keys, with four reference parameters (dhcp4, addresses, routes, nameservers), embedded in step 3 and flagged."
>
  <svg
    viewBox="0 -40 600 505"
    width="100%"
    xmlns="http://www.w3.org/2000/svg"
    role="img"
    aria-label="Candidate structure of a task topic mixing concept and reference content"
    style="max-width: 620px; display: block; margin: 0 auto;"
  >
    <defs>
      <marker id="mixed-arrow-accent" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
        <path d="M 0 1.5 L 8 5 L 0 8.5 z" style="fill: var(--diagram-accent);"/>
      </marker>
      <marker id="mixed-arrow-ink-muted" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
        <path d="M 0 1.5 L 8 5 L 0 8.5 z" style="fill: var(--diagram-ink-muted);"/>
      </marker>
      <marker id="mixed-arrow-error" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
        <path d="M 0 1.5 L 8 5 L 0 8.5 z" style="fill: var(--diagram-error);"/>
      </marker>
      <marker id="mixed-arrow-warning" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
        <path d="M 0 1.5 L 8 5 L 0 8.5 z" style="fill: var(--diagram-warning);"/>
      </marker>
      <marker id="mixed-arrow-info" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
        <path d="M 0 1.5 L 8 5 L 0 8.5 z" style="fill: var(--diagram-info);"/>
      </marker>
    </defs>

    <g class="diagram-classification" aria-hidden="true">
      <text x="90" y="-16" text-anchor="middle" font-size="11" font-weight="700" style="fill: var(--diagram-ink); text-transform: uppercase; letter-spacing: 0.06em;">Concept</text>
      <text x="300" y="-16" text-anchor="middle" font-size="11" font-weight="700" style="fill: var(--diagram-ink); text-transform: uppercase; letter-spacing: 0.06em;">Task</text>
      <text x="510" y="-16" text-anchor="middle" font-size="11" font-weight="700" style="fill: var(--diagram-ink); text-transform: uppercase; letter-spacing: 0.06em;">Reference</text>
    </g>

    <path d="M 300 42 L 300 72" fill="none" style="stroke: var(--diagram-accent); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-accent)" />
    <path d="M 300 117 L 300 147" fill="none" style="stroke: var(--diagram-accent); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-accent)" />
    <path d="M 300 192 L 300 222" fill="none" style="stroke: var(--diagram-accent); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-accent)" />
    <path d="M 300 267 L 300 297" fill="none" style="stroke: var(--diagram-accent); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-accent)" />
    <path d="M 300 342 L 300 372" fill="none" style="stroke: var(--diagram-accent); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-accent)" />
    <path d="M 160 21 L 227 21" fill="none" style="stroke: var(--diagram-error); stroke-width: var(--diagram-connector-width-emphasis); stroke-dasharray: 4 3;" marker-end="url(#mixed-arrow-error)" />
    <g transform="translate(194, 21)">
      <rect x="-29" y="-8" width="58" height="16" rx="3" style="fill: var(--diagram-surface); stroke: var(--diagram-error); stroke-width: 1px;" />
      <text x="0" y="3.5" text-anchor="middle" style="fill: var(--diagram-error); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">precedes</text>
    </g>
    <path d="M 160 246 L 227 246" fill="none" style="stroke: var(--diagram-ink-muted); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-ink-muted)" />
    <g transform="translate(194, 246)">
      <rect x="-18" y="-8" width="36" height="16" rx="3" style="fill: var(--diagram-surface); stroke: var(--diagram-ink-muted); stroke-width: 1px;" />
      <text x="0" y="3.5" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">note</text>
    </g>
    <path d="M 160 321 L 227 321" fill="none" style="stroke: var(--diagram-warning); stroke-width: var(--diagram-connector-width-emphasis); stroke-dasharray: 2 3;" marker-end="url(#mixed-arrow-warning)" />
    <g transform="translate(194, 321)">
      <rect x="-21" y="-8" width="42" height="16" rx="3" style="fill: var(--diagram-surface); stroke: var(--diagram-warning); stroke-width: 1px;" />
      <text x="0" y="3.5" text-anchor="middle" style="fill: var(--diagram-warning); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">note?</text>
    </g>
    <path d="M 440 246 L 373 246" fill="none" style="stroke: var(--diagram-error); stroke-width: var(--diagram-connector-width-emphasis); stroke-dasharray: 4 3;" marker-end="url(#mixed-arrow-error)" />
    <g transform="translate(406, 246)">
      <rect x="-29" y="-8" width="58" height="16" rx="3" style="fill: var(--diagram-surface); stroke: var(--diagram-error); stroke-width: 1px;" />
      <text x="0" y="3.5" text-anchor="middle" style="fill: var(--diagram-error); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">embedded</text>
    </g>
    <path d="M 20 246 L 8 246 L 8 447 L 592 447 L 592 246 L 583 246" fill="none" style="stroke: var(--diagram-info); stroke-width: var(--diagram-connector-width);" marker-end="url(#mixed-arrow-info)" />
    <g transform="translate(300, 447)">
      <rect x="-46" y="-8" width="92" height="16" rx="3" style="fill: var(--diagram-surface); stroke: var(--diagram-info); stroke-width: 1px;" />
      <text x="0" y="3.5" text-anchor="middle" style="fill: var(--diagram-info); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">explains dhcp4</text>
    </g>
    <g transform="translate(230, 0)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Static IP address</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Goal &bull; lines 3–4</text>
    </g>
    <g transform="translate(230, 75)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Open YAML file</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Step 1 &bull; line 13</text>
    </g>
    <g transform="translate(230, 150)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Disable DHCP</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Step 2 &bull; line 14</text>
    </g>
    <g transform="translate(230, 225)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Add static settings</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Step 3 &bull; line 15</text>
    </g>
    <g transform="translate(230, 300)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Run netplan try</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Step 4 &bull; line 41</text>
    </g>
    <g transform="translate(230, 375)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-accent); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Confirm</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Step 5 &bull; line 46</text>
    </g>
    <g transform="translate(20, 0)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-info); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Renderer model</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Concept &bull; lines 6–11</text>
    </g>
    <g transform="translate(20, 225)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-info); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">DHCP + static</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Concept &bull; lines 38–39</text>
    </g>
    <g transform="translate(20, 300)">
      <rect width="140" height="42" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-warning); stroke-width: var(--diagram-border-width-emphasis); stroke-dasharray: 4 2;" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Rollback timer</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-warning); font-family: var(--font-label); font-size: 0.625rem; font-weight: 600;">Concept? &bull; lines 43–44</text>
    </g>
    <g transform="translate(440, 204)">
      <rect width="140" height="84" rx="4" style="fill: var(--diagram-surface); stroke: var(--diagram-ink-muted); stroke-width: var(--diagram-border-width-emphasis);" />
      <text x="70" y="19" text-anchor="middle" style="fill: var(--diagram-ink); font-family: var(--font-sans); font-size: 0.8125rem; font-weight: 600;">Interface keys</text>
      <text x="70" y="33" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">Reference &bull; lines 31–36</text>
      <line x1="12" y1="42" x2="128" y2="42" style="stroke: var(--diagram-rule); stroke-width: 1px;" />
      <text x="70" y="58" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">dhcp4 &bull; addresses</text>
      <text x="70" y="73" text-anchor="middle" style="fill: var(--diagram-ink-muted); font-family: var(--font-label); font-size: 0.625rem;">routes &bull; nameservers</text>
    </g>
  </svg>
</Diagram>

### Deterministic checks

Code then applies a validation contract that the team declared for task topics:

- **R1:** Steps form one ordered path from the goal. `ok`
- **R2:** Every reference parameter declares its accepted values. `ok`
- **R3:** Every concept relationship resolves to a declared node. `ok`: *DHCP + static* resolves to `dhcp4`.
- **R4:** Only the goal and prerequisites precede the steps. `nok`
- **R5:** A step embeds at most two reference parameters. `nok`: step 3 embeds four.
- **R6:** A step note contains no more than two sentences, like DITA's `<info>`. `ok` for lines 38–39; `dunno` for lines 43–44, because their classification as a step note is uncertain.

R6 works on two levels. Counting sentences is deterministic. Deciding whether a passage is a step note in the first place is the model’s probabilistic call, and lines 43–44 might instead describe the step result. None of these rules says mixing is wrong. R5 and R6 let some reference and concept material in, and their thresholds are editorial choices, not truths the validator discovers. The code only establishes that the extracted model breaks two declared rules, not that the model reflects the prose (see What structural validation can and cannot prove).

### The validation report

The report gives the author something to act on:

```text
configure-static-ip.md  nok  (contract: task topic)

nok    lines 6-11   concept, high confidence
       "How Netplan works" sits between the goal and step 1.
       R4: only the goal and prerequisites may precede the steps.
nok    lines 31-36  reference, 4 parameters, high confidence
       Step 3 embeds a table of Netplan keys.
       R5: a step may embed at most two reference parameters.
dunno  lines 43-44  step note or step result, low confidence
       R6: step note status uncertain; sentence count not decisive.
       Review: rationale for netplan try, or what the step does?
ok     R1 sequence, R2 accepted values, R3 concept links
```

The fix it suggests is an old DITA habit: keep the task to its goal and steps, move the table into a reference topic and How Netplan works into a concept topic, and link the three. If nobody will reuse those keys, keeping the table and relaxing R5 for this topic is also a valid answer. The report asks for a decision, not a split: the model proposes, the code checks, and a human decides.

## Why Markdown syntax isn't sufficient

A validator has to keep three layers apart:

- **Syntax:** the headings, lists, tables, and code fences that Markdown declares.
- **Semantic relationships:** the transitions, prerequisites, conceptual dependencies, and links between resources that the prose describes.
- **Structural rules:** what those relationships must satisfy for a given reader purpose.

Documentation contains relationships that Markdown syntax alone cannot express. An ordered list may hold dependent steps, prioritized tips, or independent options. Headings rarely form a strict conceptual tree. A structural validator must therefore infer these relationships rather than assume them from formatting, and then apply rules that fit what the document is for.

## Grounding validation in reader purposes

This approach borrows DITA’s discipline, not its guarantees. In DITA, the structure is fixed before a word is written. Here, it is inferred afterward:

No single structural model fits all documentation. A no-loops rule that protects a tutorial from circular prerequisites would wrongly reject a troubleshooting guide's retry loop. A reachability rule that suits a procedure means nothing for an API reference. The rules must depend on what the reader is trying to do.

To keep that choice predictable, the model picks from a small, provisional taxonomy rather than inventing categories. Three terms stay distinct:

Reader purpose
: What the reader wants to accomplish.

Candidate structure
: The entities and relationships that the model infers from the content.

Validation contract
: The purpose-specific rules that deterministic code applies to that structure.

Reader purposes describe outcomes, not titles: a “Getting started” page might be a tutorial or a procedure, and each needs different checks. Real documents also mix purposes, so a validator would need to evaluate sections separately or report the ambiguity.

The taxonomy has five reader purposes, each with its own candidate structure:

<ResponsiveTable
  caption="Table 2: Reader purposes, candidate structures, and validation contracts"
  columns={["Reader purpose", "Reader goal", "Candidate structure", "Validation contract focus"]}
  rows={[
    [
      "<strong>Procedure</strong>",
      "Complete a task.",
      "Linear sequence",
      "Single start; goal reachable; no dead-end steps.",
    ],
    [
      "<strong>Tutorial</strong>",
      "Learn a skill progressively.",
      "Prerequisite structure",
      "Prerequisites come first; no circular dependencies.",
    ],
    [
      "<strong>Explanation</strong>",
      "Understand concepts and design rationale.",
      "Concept map",
      "Relationships cite textual evidence; feedback loops allowed.",
    ],
    [
      "<strong>Reference</strong>",
      "Look up precise specifications.",
      "Entities with structured attributes",
      "Schema conformity; required attributes present; identifiers resolve.",
    ],
    [
      "<strong>Troubleshooting</strong>",
      "Diagnose and recover from a fault.",
      "Diagnostic flow with retry loops",
      "Checks branch on success and failure; retry loops have exits; paths end in recovery or escalation.",
    ],
  ]}
/>

Navigation maps and release timelines, which serve readers looking for the right page or tracking what changed, are outside the scope of this proposal. They could be considered in future extensions.

## Candidate documentation structures

The five structures fall into three families: procedures, concepts, and reference and troubleshooting. Each figure shows the shape; the bullets give what a validator checks and what it can’t establish.

### Procedures: linear sequences

- Steps form a single path from one entry point to one goal. A validator checks that the goal is reachable and that no step is a dead end.
- A numbered list isn't proof of dependency, and real procedures often include optional or recovery steps.

### Concepts: prerequisite structures and concept maps

- Topics depend on prerequisites. A validator checks that prerequisites come first and rejects circular dependencies, which would deadlock the learner.
- It models formal prerequisites, not how readers actually skip ahead.

- Concepts connect through labeled relationships. A validator checks that every relationship links concepts grounded in the text.
- Feedback loops are legitimate here, and a connected map doesn't prove a clear explanation.

### Reference and troubleshooting: structured entities and diagnostic flows

- Entities such as API endpoints or CLI flags carry typed attributes. A validator checks schema conformity, required attributes (such as authentication), and identifier resolution.
- It can't judge whether the descriptions are clear, accurate, or complete.

- Checks, corrective actions, and retry loops lead to resolution or escalation. A validator checks that every check branches on both results and that every retry loop has an exit.
- It can show that readers won't loop forever, not that they'll fix the fault.

## The validation pipeline

Each of the five stages has one owner:

1. **Parse (conventional tools):** A Markdown parser extracts the syntax tree and source line numbers.
2. **Classify (AI):** A model proposes the reader purpose, cites supporting passages, and flags ambiguity.
3. **Extract (AI):** A model proposes the candidate structure, linking every relationship to its source passage.
4. **Validate (deterministic code):** Code evaluates the candidate structure against the validation contract for its reader purpose.
5. **Report (CI):** The pipeline combines the checks with extraction confidence and reports one of three outcomes.

AI proposes the structure; it never certifies it. And because inference is involved, pass or fail isn’t enough: the pipeline must also be able to say it doesn’t know.

<ResponsiveTable
  caption="Table 3: Validation outcomes and recommended actions"
  columns={["Result", "What the validator established", "Suggested CI action"]}
  rows={[
    [
      "<strong>ok</strong><br/><span class=\"font-label text-xs text-ink-muted\">[PASS]</span>",
      "Structural checks pass on a structure extracted with sufficient evidence.",
      "<code>exit 0</code>: Pass the build, or start in advisory mode."
    ],
    [
      "<strong>nok</strong><br/><span class=\"font-label text-xs text-ink-muted\">[FAIL]</span>",
      "A structural rule violation is established on a confidently extracted structure, such as an unreachable step, an incomplete branch, or a circular dependency where the contract prohibits it.",
      "<code>exit 1</code>: Block or flag the pull request, citing the elements, source lines, and violated rule."
    ],
    [
      "<strong>dunno</strong><br/><span class=\"font-label text-xs text-ink-muted\">[REVIEW]</span>",
      "Interpretation or extraction is too uncertain to establish a reliable result.",
      "<code>warn</code>: Route to human review, separate from confirmed violations."
    ]
  ]}
/>

## What structural validation can and cannot prove

Four properties are easy to conflate:

Structural correctness of the candidate model
: The extracted structure satisfies its validation contract. Deterministic code can establish this with certainty, but that doesn’t prove the model accurately represents the source documentation.

Completeness of extraction
: The structure captures every step, condition, and relationship in the prose. A model can miss a branch phrased idiomatically, and the checker never sees what wasn’t extracted.

Semantic accuracy
: The structure means what the prose means. A model can invent a step or invert a condition. Evidence links make such errors inspectable, not impossible.

Interpretation uncertainty
: How far the pipeline can trust the extraction. When uncertainty is high, the honest result is dunno.

A structurally valid graph proves a property of the graph. It doesn’t prove that the AI read the source correctly, and even an accurate model doesn’t prove that the documentation is factually correct, complete, clear, or useful.

## Testing the hypothesis

Authors keep writing plain Markdown, so an experiment could run in advisory mode on pull requests. It would start with procedures and troubleshooting guides, whose semantics are the most tractable, and combine a Markdown parser, a schema-constrained extraction prompt with source citations, a deterministic rule checker, and a runner that records results without blocking builds.

To show value beyond linting, it would need to measure:

- **Consistency:** Does the model assign the same reader purpose across runs and model versions?
- **Agreement:** How often does the extracted structure match what experienced technical writers see?
- **Sensitivity:** When known defects (circular prerequisites, unreachable steps, missing exit conditions) are seeded into test fixtures, does the pipeline flag them?
- **Error rates:** How often does it invent transitions or miss real branches?
- **Dunno rate:** Is the share of inconclusive results low enough to be practical?
- **Baseline:** Run conventional linters such as markdownlint and Vale on the same fixtures. Which defects does only the pipeline catch, and at what cost in false alarms?

Until those numbers exist, AI-assisted structural validation remains a hypothesis: promising, but still a hypothesis.

## External sources

- [Docs-as-code principles](https://www.writethedocs.org/guide/docs-as-code/)

<small>*Hero image: ["Measuring instrument"](https://www.rawpixel.com/image/5903918/photo-image-white-background-public-domain-person) via [rawpixel](https://www.rawpixel.com/), originally from [PxHere](https://pxhere.com/en/photo/935292), licensed under [CC0](https://creativecommons.org/publicdomain/zero/1.0/).*</small>

---

Source: https://redaction-technique.org/markdown-simplicity-dita-rigor-ai-validation
