The technicality of writing
After twenty years of staring at keyboards, I have come to a realization: all the fiddly, pedantic little habits we technical writers invented to stop human beings from setting their own server racks on fire… turn out to be the exact same things preventing computers from doing it instead.
Now, most people in the industry think topics, data keys, and relationship tables are just tidy little ways of keeping vast, sprawling mountains of text from toppling over. They think our sparkling prose is the real craft, and the underlying XML is just the ugly scaffolding holding it up.
They are wrong.
The sentences are the exhaust pipes.
This matters today more than ever, because the latest creature to read your work isn’t a tired software engineer on a Thursday afternoon—it is an artificial intelligence. And an AI demands precisely what a meticulous human reader always demanded, except it has all the patience of a caffeinated toddler.
Stay with me on this, because across six interconnected headaches, I am going to show you how the whole contraption actually works.
On sentences
Clear sentences, delivered in the correct order, to a person who desperately needs them.
The ancient Romans knew this. They split the business of rhetoric into five neat compartments: inventio, dispositio, elocutio, memoria, pronuntiatio. Now, in modern boardrooms, people only ever bleat about style. But style is just the chrome trim. Arrangement and memory—deciding what goes first, what gets repeated, and what the poor sod reading it will actually need to find again—that is the gritty, oily engine work we do all day.
Back in 1981, Linda Flower and John Hayes pointed out that a page of text is essentially just the physical footprint of a plan. We’ve all seen drafts where the grammar is utterly immaculate, yet the document is an absolute trainwreck. That’s because the plan upstream was fundamentally broken, and no amount of pretty adjectives can disguise a chassis made of cheese.
On readers
In the 1960s, a chap named Robert Horn came up with “Information Mapping”. His theory was wonderfully straightforward: chop your text into bite-sized morsels, slap a bold label on each one explaining what it is, and keep related bits together.
Then in 1988, John Sweller supplied the cold, biological truth: human working memory is pathetic. It is an agonizing bottleneck. The academics used to think you could juggle seven things in your head at once; turns out it’s more like four. Every surplus paragraph you force a reader to decode is brain-bandwidth stolen from actually understanding the machinery.
If you have ever quarantined a lethal danger inside an amber warning box, or chopped a sprawling mess of prose into neat numbered steps, congratulations. You were applying cognitive load theory. More importantly, you were typing your content. A high-voltage warning is not a step. It is an entirely different mechanical component, and treating it as one is where our salvation begins.
On conversations
In 1975, a philosopher named Paul Grice pointed out that decent conversation requires following four absurdly civilized rules: Say only what is needed. Say only what you can prove. Stay relevant. And don’t waffle.
Every corporate style guide on earth is just Grice in a high-visibility jacket. Killing fluff is Quantity. Tracing every parameter back to an engineering ticket is Quality. Forcing a topic to answer only one question is Relation.
Editors have been standing over writers with heavy spanners enforcing these rules for centuries. But Quality—demanding genuine evidence before making a claim—is the one thing a computer cannot be trusted with for five seconds on its own.
On content and context
In 1969, three IBM engineers—Goldfarb, Mosher, and Lorie—had a stroke of pure brilliance. They said: tell the computer what a piece of text is (a heading, a parameter, a warning), and leave how it looks on the page to someone else. That birthed GML, which gave us SGML, which eventually gave us XML.
Around the same time, John Carroll published The Nurnberg Funnel, arguing that human beings don’t want to read a magnificent theological treatise on software; they just want to complete a task and bugger off down the pub. Combine Carroll’s task-driven minimalism with Goldfarb’s markup, and you get the bedrock of DITA: concept, task, and reference, kept strictly apart and engineered for reuse.
On OASIS
Eventually, IBM handed DITA over to OASIS—a non-profit standards body that sounds like an international treaty organization, but basically ensures no single mega-corporation owns the format.
Programmers later coined a very smug acronym for this: DRY. Don’t Repeat Yourself. The doctrine states that every single scrap of knowledge must live in one, and only one, unambiguous place.
In DITA, that is a key definition. If a network timeout is 30 seconds, you define it once in a central map. You do not copy and paste the number thirty across fifty-eight separate files. Technical writers were doing this long before developers started putting it on t-shirts, which is why taking a clean architecture and “flattening” it into static markdown feels like trading a precision German sports car for a skateboard with a wobbly wheel.
On associative trails
In 1945, Vannevar Bush dreamed up a machine called the memex, which used “associative trails”—meaningful paths carved between documents that others could trace.
Ted Nelson called it hypertext. Tim Berners-Lee built the World Wide Web out of it. And then the world ruined it by turning hyperlinks into fragile blue strings of HTML that break the moment an engineer sneezes at an endpoint.
A DITA relationship table is what Bush actually had in mind. A writer asserts that two topics belong together, types the relationship, versions it in Git, and the compiler turns it into reality. It is not a guess; it is an engineered, traversable map. The documentation repository was already a structured knowledge graph all along; we just had to build the engine to drive it.
On the DevOps loop
While we were doing that, the software engineers bolted twin turbochargers to their workflows. Git, pull requests, automated linters, and CI/CD pipelines arrived.
Google wrote books about treating documentation like code—with owners, bugs, and tests. Splendid. Except for one glaring problem. In the modern pipeline, building, testing, deploying, and monitoring are fully automated. But the actual writing? That is still an exhausted human being squinting at a complex Git diff, weeping quietly, and trying to decipher what the developers changed. Every other stage got handed to a machine. Drafting is the lone bottleneck left in the shed.
On models
Which brings us to the Large Language Model.
It is the newest recruit to the team, and it is a reckless idiot. It reads what is in front of it, encounters a gap, and cheerfully hallucinates a complete fabrication because it sounds pretty. Left to its own devices, it shatters Grice’s Quality maxim every hour on the hour.
Our old structural pedantry is the only seatbelt that works:
- Information types tell it what kind of document it is allowed to produce.
- Keys stop it from inventing numbers.
- Relationship tables force it to stick to approved roads.
- Schemas cage its output in rigid iron bars.
None of this was invented for generative AI. It was invented for sleep-deprived human readers, which is why it actually holds up.
The iron law is simple: the model proposes, but the code checks decide.
The AI may draft the sentences, but a cold, heartless Python script audits every flag, integer, and hyperlink against the master repository before it ever sees production.
Table 1
Table 1 Each row is a judgement that moved out of someone’s head and into the file.
And what of us?
Does this replace the technical writer?
No.
A machine has no taste. It has no judgment. It cannot figure out what an engineer actually needs when their cluster is melting down at 3:00 AM. It cannot design a taxonomy, and it cannot tell whether a sentence is true in the way that matters.
Those jobs remain with us. What changes is that we can finally stop wasting forty hours a week manually changing “128” to “256” across four hundred identical files.
From the table to the build.
Each one takes a row from the table and carries it one stage further.
Migrate DITA to docs as code and prove nothing was lost, with keys, content references and conditions kept as real reuse.
Builds on DRY and DITA reuse
A first-draft documentation pull request on every code merge, so the writer reviews a draft instead of starting from a diff.
Builds on docs as code
Answers that cross documentation silos by walking the links writers already keep, with every step cited.
Builds on Bush's trails
New DITA topics drafted from the ones you already have, with the schema acting as the guardrail.
Builds on information types
Regulator-ready evidence built from the DITA source and the approvals Git already records.
Builds on Grice's quality maxim
Answers scoped to the hardware generation a reader actually runs.
Builds on keys and profiling
If your work looks like mine, you have probably built a good deal of this already. I would like to hear where it holds up and where it breaks.
Siddharth Rao, October 2026