Part 4 · AlignR · DITA · Generative AI · 14 min read

Drafting TPU7x from v6e: let the schema guard the first draft

Every time the silicon wizards bolt on a bigger heatsink and declare a new hardware generation, we are expected to retype the exact same twelve manuals by hand with slightly larger numbers. Here is how we stop doing that, why letting an LLM generate raw XML is a brilliant way to burn your house down, and how strict schemas keep the whole circus from careening off the rails.

Siddharth Rao · technical writing

Portfolio post, written as an internal knowledge-sharing post for Google's data center documentation team. Google hasn't engaged, sponsored or endorsed this work. Sample content is adapted from Google Cloud TPU documentation under CC BY 4.0 ²⁰. Savings figures are projections from the stated assumptions, not measurements.

Fig. 0The model drafts inside a schema. Code writes the XML. Checks decide.

Fig. 1Recent Cloud TPU documentation milestones. Release dates from the Cloud TPU release notes ¹; last-updated dates from each generation's page ²³⁴. A hardware launch isn't a neat, one-off sprint; it is an initial page drop, followed by an endless loop of Preview-to-GA edits, capped by endless retroactive patching of every legacy manual in the fleet.

Ironwood reached Preview as TPU7x in November 2025 and stumbled through the tape to GA in March 2026 ¹. Trillium (v6e) went GA back in December 2024 ¹. And on every single one of those occasions, the documentation department was expected to produce an identical fleet of technical pages: the architectural breakdown, the specification table, the list of supported topology slices, the VM configuration details, and a massive training guide. In terms of narrative structure, these documents have all the variety of a train timetable. The chassis is identical; only the numbers, and perhaps one or two genuinely new engineering ideas, ever change.

And how do we currently draft this magnificent armada? The exact same way every sensible technical writer does when confronted with a soul-crushing deadline: we open last year's page, hit "Save As", and spend the next four weeks manually changing every single integer by hand, hoping against hope that our peer reviewers spot the thirty-two typos we undoubtedly introduced along the way. It works, in the same way that crossing the Atlantic in a rowing boat works. But it is profoundly ridiculous that our most predictable, formulaic writing assignment is conducted with less automation than a 19th-century weaving loom.

Which brings us to AlignR ⁵. It is a system we have been designing that treats documentation generation like an actual assembly line. We shall examine it through two distinct sets of eyes—first the weary writer, then the exasperated engineer—before taking a cold, hard look at the balance sheet to see if the bean-counters should care.

v5p · v6e · TPU7x

On sibling pages

Line up the reference pages for v5p, v6e, and TPU7x side by side, and the sheer lack of imagination is breathtaking. Every single one features an introductory preamble, a system architecture matrix, a supported configurations section, and a VM breakdown. But because three different human beings drafted these in three different years with three different coffee habits, the section labels have wandered all over the shop.

Fig. 2Headings and opening sentences as published ²³⁴. Four slots are identical across every generation. The dark row at the bottom is where a technical writer actually earns their dinner—and conveniently, it's the only row you can't simply copy from last year's homework.

Fig. 3The same fact, typed twice, with two units. Added to illustrate the drift described in the text.

And then there is the numbers drift. This is the bit that makes readers want to throw their monitors out of the window.

Seen on the live TPU7x pageIn the specification table, the HBM capacity is listed as 192 GiB and the bandwidth as 7380 GBps. Turn the page to the memory hierarchy overview, and it cheerfully declares that each chip possesses 192 GB of HBM, running at approximately 7.37 TB/s ². GiB and GB are not the same thing. It is like a car brochure telling you the fuel tank holds 60 litres on page four, and 60 gallons on page five. Nobody committed deliberate sabotage; someone just typed the number twice, by hand, into two different text boxes.

In DITA, we solved this twenty years ago using keys. You define tpu7x-hbm-capacity once in the master map, reference it everywhere, and the table and the prose are physically incapable of contradicting each other. The problem isn't the XML. The problem is that when you are under ferocious launch pressure, manually wiring eighty separate keys into forty XML topics is enough to drive any writer stark raving mad.

JSON Schema · RELAX NG

On schemas

AlignR is built on Google's open-source Agent Development Kit ¹⁹. It digests three assets we already maintain: an authoritative YAML facts file with the new generation's numbers, the existing DITA repository containing the older generations, and our structural content model. It then drafts the new manual set and files a neat pull request for every topic.

The entire system is anchored by one golden rule: Gemini is never, ever allowed to write raw XML. If you ask an LLM to generate raw XML, it will sooner or later drop a closing tag, invent an imaginary namespace, or construct an element tree that looks like an explosion in a pasta factory. Instead, Gemini is forced to output clean, structured JSON against an inflexible JSON Schema ⁶. Boring, predictable, unglamorous Python code converts that JSON into DITA XML. And then the XML has to run a gauntlet of deterministic linting engines before a human being is even asked to look at it.

Fig. 4The language model sits firmly in a padded cell. Python code decides what it gets to see, schemas dictate what it is allowed to return, and strict linters decide if its homework is fit for human consumption. The full architecture is detailed in the AlignR design document ⁵.

The two schemas enforce totally different boundaries. The JSON Schema is generated dynamically on the fly for each specific run, containing strict enums that restrict the model to only existing key references and cited source IDs. Gemini literally cannot invent a phantom specification key, because the API's structured output engine will refuse to emit the tokens ⁶. Then, the normative OASIS DITA RELAX NG grammar verifies that the compiled XML is completely valid. Finally, our grounding checker executes Google's recommended practice: programmatic validation in application code ⁶.

Stage	Runs on	Stops
Gate 1: JSON Schema	Gemini API, at generation	Missing fields, hallucinated keys, invalid data types, incorrect list counts
Serialiser	Python	Hardcoded literal numbers (swapped for keys), unmarked uncertainties (swapped for draft comments)
Gate 2: DITA grammar	lxml, OASIS RELAX NG	Syntactically broken XML, invalid element hierarchies
House rules	ISO Schematron⁹	Raw numbers inside tables, formatting deviations from sibling chapters
Grounding	Python	Unattributed figures, units written as GB when the spec sheet says GiB
Style	Vale, Google package¹⁰	Passive voice, style guide infringements, corporate jargon

Through the writer's lens

On writers and review

Ask any enterprise technical writer about hardware launch week, and they will describe the exact same recurring nightmare. The manual copying is mind-numbing. The risk of a missed specification slipping into production keeps you awake at 3:00 AM. And the genuinely novel technical concepts—the parts that actually require human explanation—get shoehorned into whatever desperate minutes remain before the press release goes live.

AlignR flips the entire script. Instead of facing forty blank pages, the writer receives an automated pull request with four guarantees:

The DITA is already valid. It cleared RELAX NG and Schematron before pinging your notifications. You will not waste twenty minutes tracking down an unclosed tag.
Every specification is tethered to a key. Raw numbers are banned from the text. The GiB vs. GB comedy cannot happen, because mismatched units fail the grounding linter instantly.
Gaps are marked as questions, not creative fiction. When source data is missing, the agent does not hallucinate a believable number. It drops an explicit <draft-comment> tagging the engineer. Because processors suppress draft comments by default ⁸, internal confusion can never leak to customers.
Writers spend their time on what is actually new. Routine sibling topics arrive ninety percent complete. Radical new hardware features—like the TPU7x dual-chiplet interconnect—arrive as structured stubs with highlighted questions. That is where human judgment belongs.

Below is the source output. First, the master key definitions, compiled directly from the engineer's raw data sheet into a single source of truth.

maps/tpu7x-keys.ditamapgenerated from the facts file · excerpt

<map>
  <title>TPU7x values</title>
  <keydef keys="tpu7x-chips-per-pod">
    <topicmeta><keywords><keyword>9,216</keyword></keywords></topicmeta>
  </keydef>
  <keydef keys="tpu7x-bf16-tflops">
    <topicmeta><keywords><keyword>2,307 TFLOPs</keyword></keywords></topicmeta>
  </keydef>
  <keydef keys="tpu7x-hbm-capacity">
    <topicmeta><keywords><keyword>192 GiB</keyword></keywords></topicmeta>
  </keydef>
  <keydef keys="tpu7x-hbm-bandwidth">
    <topicmeta><keywords><keyword>7,380 GBps</keyword></keywords></topicmeta>
  </keydef>
  <!-- one keydef per row in the specification table -->
</map>

Values taken from the TPU7x data sheet ². The numbers live here and only here. AlignR's schema prevents Gemini from using anything other than these canonical keys.

And here is the drafted system architecture topic. The layout mirrors the v6e sibling, the values resolve via keys, and the lingering unit dispute is flagged plainly for the hardware engineer.

topics/tpu7x/system-architecture.ditadrafted by AlignR · abridged

<reference id="tpu7x-system-architecture" xml:lang="en-US">
  <title>TPU7x system architecture</title>
  <shortdesc>Each TPU7x chip contains two TensorCores and four SparseCores.</shortdesc>
  <refbody>
    <properties id="specs">
      <prophead><proptypehd>Specification</proptypehd><propvaluehd>TPU7x</propvaluehd></prophead>
      <property><proptype>Number of chips per Pod</proptype>
        <propvalue><ph keyref="tpu7x-chips-per-pod"/></propvalue></property>
      <property><proptype>HBM capacity per chip</proptype>
        <propvalue><ph keyref="tpu7x-hbm-capacity"/></propvalue></property>
    </properties>
    <section id="memory"><title>Memory hierarchy</title>
      <p>Each chip has <ph keyref="tpu7x-hbm-capacity"/> of high-bandwidth memory (HBM).</p>
      <draft-comment author="alignr" disposition="open">
        For the engineer: S1 gives HBM as 192 GiB. S2 gives 192 GB. Which unit is correct?
      </draft-comment>
    </section>
  </refbody>
</reference>

Underlined: canonical key references compiled by Python. Red: a blocking review comment that prevents conflicting units from reaching the production website.

Fig. 5Projected writer hours for one 12-topic launch set. Industry drafting baseline from TechScribe ¹¹; the 2-hour review estimate targets our 40% maximum-edit threshold. Crucially, the time allocated to explaining difficult, genuinely new architecture doesn't shrink by a single second.

What does this mean in practice? We modelled a standard 12-topic hardware release: 9 sibling-derived topics and 3 brand-new architectural concepts. Using established industry baselines of 5 hours to draft an online topic from scratch ¹¹, a manual launch eats 60 hours. With AlignR, sibling reviews take 2 hours each, while the 3 complex new concepts still get the full 5 hours of dedicated human attention.

The time AlignR saves is the mindless copy-paste drudgery. The time it protects is the work where a skilled writer explains complex engineering that has never existed before.

Dashed outlines mark projected values. The stamp-red block is the hour of questions. The pale red blocks, the genuinely new concepts, do not shrink.

Through the developer's lens

On developers and Git

Two groups of developers collide with launch documentation. The hardware engineer owns the raw numbers: core counts, memory bus widths, supported interconnect configurations. The software engineer has to consume those docs to write functional code. Both are currently poorly served.

The hardware engineer is dragged into reviewing sprawling, forty-page documents simply to check six numbers, with no automated diffs and questions arriving in fragmented chat threads. Meanwhile, the software engineer spends thirty minutes a day searching for documentation that invariably turns out to be contradictory ¹⁵.

AlignR puts documentation onto standard software engineering rails: Git branches, automated tests, clean diffs, and pull requests ¹⁷. The engineer's responsibility shrinks to two tasks they already understand: updating a clean YAML facts file, and answering a focused code review comment.

Fig. 6The facts file lives directly inside the engineer's codebase. Merging it triggers AlignR in CI, opening an automated documentation pull request protected by the exact same branch protection rules as production code ¹⁸. Both release simultaneously on the exact same git tag.

The facts file is deliberately unexciting. It is plain YAML stored in the repository, anchoring every single numerical value to an explicit source citation. That source ID allows our grounding validator to prove the lineage of every integer down to the exact commit.

facts/tpu7x.yamlowned by the product engineer · excerpt

generation: tpu7x
sources:
  S1: "TPU7x specification table"
  S2: "TPU7x memory hierarchy section"
facts:
  chips-per-pod:   { value: 9216, unit: chips, source: S1 }
  bf16-tflops:     { value: 2307, unit: TFLOPs, source: S1 }
  hbm-capacity:    { value: 192, unit: GiB, source: S1 }
  machine-type:    { value: tpu7x-standard-4t, source: S1 }
  software-version: null   # unknown at draft time: becomes a question

Values taken from the TPU7x documentation ². A null value doesn't cause the build to explode; it automatically compiles into a targeted draft comment assigned to the code owner.

That null is vital. When drafting the TPU7x training guide, Gemini helpfully copied a legacy software version flag pattern from the older v6e chapter. It looked completely plausible. But because no source citation existed in the facts file, the grounding test failed the step, the agent revised the block, and the engineer was pinged with a single question instead of being handed a twenty-page paper to proofread:

topics/tpu7x/train-a-model.ditadrafted by AlignR · step 4 of 6

<step>
  <cmd>Create the TPU VM with the TPU7x machine type.</cmd>
  <info>
    <p>Use the <ph keyref="tpu7x-machine-type"/> machine type. All TPU7x slices use it.
      <draft-comment author="alignr" disposition="open">
        For the engineer: which TPU software version does TPU7x use?
        The v6e sibling uses a version flag. No source gives one for TPU7x.
      </draft-comment>
    </p>
  </info>
</step>

The TPU7x page explicitly specifies the tpu7x-standard-4t machine type ². That fact is mathematically grounded. The unconfirmed software flag was not, so it was demoted to a review question.

And the rules that enforce this governance are standard ISO Schematron rules maintained by the information architect ⁹. An engineer can inspect them exactly like an ESLint configuration:

rules/house.schone rule of six

<sch:pattern id="spec-values-use-keys">
  <sch:rule context="propvalue">
    <sch:assert test="ph[@keyref] and normalize-space(text()) = ''">
      A specification value must be a key reference, not typed text.
    </sch:assert>
  </sch:rule>
</sch:pattern>

Hand-authored and AI-drafted files are held to the exact same standard. The AI bot has no special bypass tokens, and it cannot merge its own pull requests.

Fig. 7Lift in organisational performance from engineering capabilities, grouped by documentation quality ¹⁴. Consistently accurate, rapidly published launch documentation is what separates top-tier engineering organizations from chaos.

Why should engineering leadership care about any of this? Because documentation quality directly accelerates delivery performance across the entire organisation. DORA’s multi-year research proves that teams with high-quality documentation extract drastically higher performance multipliers from their technical capabilities ¹⁴:

For the organisation

On the organisation

Writers save hours of repetitive typing, and engineers stop proofreading boilerplate. What is that worth in actual currency? Here is the financial projection for a standard 12-topic generation set. All assumptions are laid bare below.

43%fewer writer hours per generation set

4 hof engineer review back per set

$1,391in wages returned per set, before overhead

< $1model cost to draft the whole set

These calculations account strictly for base hourly wages. Once corporate benefits, real estate overhead, and payroll taxes are included, the actual savings are substantially higher. Runtime costs are effectively absorbed by Cloud Run and BigQuery free quotas.

Fig. 8Projected salary cost of one generation set. Engineer review time highlighted in pale red.

Fig. 9Annual business value scaled across generation set releases. Hours represent combined technical writer and engineer time.

And two immense dividends never show up on an accountant's spreadsheet. First, structural integrity: because every hardware value resolves from a canonical key, conflicting units like the GiB/GB catastrophe are eliminated forever. Second, cycle time: a complete draft documentation set materializes within five minutes of an engineer merging their YAML specification, rather than languishing for three weeks waiting for a writer to clear their calendar.

Input	Value	Basis
Topics in a generation set	12: 9 with a sibling, 3 new concepts	The TPU7x set in the design document⁵
Time to write an online topic	5 h (published range 4 to 6 h)	Fredrickson Learning, via TechScribe¹¹
Time to review a drafted topic	2 h	Assumption, from the 40% edit-ratio target⁵
Engineer review	6 h today (whole pages); 2 h with AlignR (questions)	Assumption
Technical writer wage	$43.46 an hour, median	BLS, May 2025¹²
Software developer wage	$135,980 a year, median; $65.38 an hour at 2,080 hours	BLS, May 2025¹³
Model cost per draft attempt	$0.033 at the 2027 standard price; 1.4 attempts per topic	Agent Platform pricing¹⁶; attempts from the design target⁵

One generation set	Today	With AlignR	Change
Writer hours	60	34	−26
Engineer hours	6	2	−4
Writer wages	$2,608	$1,478	−$1,130
Engineer wages	$392	$131	−$261
Model and runtime	$0	$0.55	+$0.55
Total	$3,000	$1,609	−$1,391 (46%)

Design choice

On fine-tuning

The initial prototype of AlignR attempted exactly that: supervised fine-tuning and RLHF using thousands of expert-annotated documentation pairs ⁵. But when you examine the unit economics, fine-tuning an enterprise LLM for technical documentation is like buying a Ferrari to deliver milk:

	Constrained generation (AlignR v0.1)	Fine-tuned model
Cost per draft attempt	$0.017 now, $0.033 from January 2027 (Gemini 3.8 Flash)	$0.034 (tuned Gemini 3.5 Flash endpoint at 1.5 times its base price)¹⁶
Before the first draft	Nothing	About $1,800 of training, plus 1,920 annotator hours⁵: about $83,400 at the writer median wage
Valid DITA	Guaranteed by the gates	Not guaranteed. A tuned model still needs the same gates.
Model generation	Current Flash model	Gemini 3.5 Flash, the newest Flash model on the tuning price list¹⁶

The human annotation effort alone costs more than eighty-three thousand dollars—wiping out the financial benefits of sixty consecutive hardware launches before you generate a single sentence. And even after fine-tuning, the model will still occasionally emit malformed XML, meaning you need the exact same validation gates anyway. Our approach stores every human edit as a preference pair in our BigQuery audit log. When a repeated stylistic mistake emerges, we turn it into an automated Schematron rule, which costs precisely zero dollars to execute.

Scope

On limits

It will not invent original architecture. If a hardware subsystem has no historical equivalent, AlignR outputs an honest structural stub with targeted questions. It leaves the creative explaining to a human.
It does not replace DITA Open Toolkit. Fast XML linters confirm syntactic validity, but the final documentation suite is still built through standard DITA-OT pipelines in CI.
It never transmits unannounced hardware specs to free-tier APIs. Free public endpoints reserve the right to ingest payloads for model training ²¹. Pre-release silicon metrics are processed strictly under commercial, zero-data-retention enterprise tiers.
The figures above remain projections. The next phase is to measure real execution performance against an active hardware program.

Next steps

On what comes next

We are executing the validation benchmark now: using historical v5p and v6e manuals to auto-draft the TPU7x documentation suite, and comparing the synthetic output against the production pages that actually shipped. We will publish the scorecard openly, including the edge cases where the automated drafts stumbled. If your product family iterates in hardware generations—whether server blades, custom silicon, or network switches—this pattern applies directly, and we should be delighted to collaborate.

The objective is not to reduce technical writing headcount. The objective is to ensure that during launch week, technical writers are actually explaining the technology, rather than spending their lives manually replacing "128" with "256" across four hundred XML files.

Siddharth

Sources

References

Google Cloud, "Cloud TPU release notes." docs.cloud.google.com/tpu/docs/release-notes
Google Cloud, "TPU7x (Ironwood)," last updated October 13, 2026. docs.cloud.google.com/tpu/docs/tpu7x
Google Cloud, "TPU v6e," last updated October 13, 2026. docs.cloud.google.com/tpu/docs/v6e
Google Cloud, "TPU v5p," last updated October 13, 2026. docs.cloud.google.com/tpu/docs/v5p
Siddharth Rao, "AlignR: Generate new DITA topics from the ones you have," design document v0.1, and the v1.0.0 design it replaces. siddharthraop.github.io/AlignR
Google AI for Developers, "Structured outputs." ai.google.dev/gemini-api/docs/structured-output
OASIS, DITA 1.3, "Recognized XML-document grammar mechanisms." dita-lang.org/1.3/dita/archspec/base/recognizedconstraintmechanisms
DITA language reference, "draft-comment." dita-lang.org/dita/langref/base/draft-comment
lxml, "lxml.isoschematron package." lxml.de/apidoc/lxml.isoschematron.html
Vale, "Google" style package. vale.sh/hub/google
TechScribe, "Documentation project metrics," citing Fredrickson Learning, Stop Guesstimating, Start Estimating. techscribe.co.uk/techw/documentation-project-metrics.htm
U.S. Bureau of Labor Statistics, "Technical Writers," Occupational Outlook Handbook. bls.gov/ooh/media-and-communication/technical-writers.htm
U.S. Bureau of Labor Statistics, "Software Developers, Quality Assurance Analysts, and Testers," Occupational Outlook Handbook. bls.gov/ooh/computer-and-information-technology/software-developers.htm
DORA, "Documentation quality." dora.dev/capabilities/documentation-quality
Stack Overflow, "2024 Developer Survey: Professional developers." survey.stackoverflow.co/2024/professional-developers
Google Cloud, "Agent Platform pricing: Generative AI." cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing
Write the Docs, "Docs as Code." writethedocs.org/guide/docs-as-code
GitHub Docs, "About protected branches." docs.github.com/.../about-protected-branches
Google, Agent Development Kit documentation. github.com/google/adk-docs
Google Developers, "Site Policies." developers.google.com/site-policies
Google AI for Developers, "Gemini Developer API pricing." ai.google.dev/gemini-api/docs/pricing

From this post to the build

Design docOpen RepositoryCode

The series

Part 1MANIFEST Part 2The Autonomous Author Part 3KnowledgeFlow Part 4AlignR Part 5AEGIS Part 6VALID

Next in the series

When the regulator reads the docs →