Why AI Technical Documentation Is So Hard to Read — and How to Fix It

I really don’t like the technical docs that Codex writes. They’re in plain Chinese, and yet they’re exhausting to read.

This article answers that question, and shows you how to use hai-simplified-technical to solve this kind of problem.

Let’s start by calling out AI-written docs. Sometimes AI will write things like this:

On the next restart, it will fail to start.

Who is “it”?

Suppose both a service and a config-agent were mentioned earlier in the text. Which one does “it” refer to? You might go look at the service — or you might go look at the config-agent. The sentence doesn’t give you enough information. The human brain has to spend energy figuring these things out.

One sentence, two possible readings — and two possible directions. AI-generated technical docs have plenty of other flaws too, and stacked together, they become very hard to read.

Why?

1 · The Sentence Isn’t Wrong — It Just Means Two Things

The most common flaw in technical docs looks, grammatically, almost fine. The problem is that each one leaves the reader a gap to guess at.

“Optimizations were made”: optimizations to what? Did we add an index, or change the cache? The action is buried in a noun; the reader only knows that something was done.

“Clean up at the appropriate time”: when is “appropriate”? The author has an answer in mind, but didn’t write it down.

“Settings, parameters, configuration”: the writer knows this is the same file — the reader thinks it’s three different things.

“It’s best to check this as soon as possible”: is this mandatory, or optional?

“Restart (if there were changes)”: the reader sees “restart” and may already be acting on it, before they’ve read the parenthetical condition.

Any one of these is a small thing. But a doc full of dozens of sentences like this means the reader has to guess once per sentence.

The Reader Has Changed

When a colleague hits something vague, they may fill in the meaning from project experience — or they may just go ask the author. Either way, that context may not have been written into the doc.

When a README, a runbook, or AGENTS.md is handed to a coding agent, the omissions in the doc become assumptions at execution time. When it reads “settings,” “parameters,” and “configuration,” it doesn’t always know whether the author meant the same file.

The cost of vagueness has changed: Vagueness no longer just confuses readers and agents — it can cause the executor to take the wrong step.

“Write It More Clearly” Can’t Be Checked

We all know docs should be written clearly. But “clearly” on its own doesn’t guide any revision: which word is ambiguous? Which condition is missing? Which sentence should be split?

Simply telling an AI to “write it more clearly” may produce more explanations and filler — while the original ambiguity is still there.

What I need is a set of checkable rules: can this word be used here? Should this sentence be split? Where should this warning go?

The Information Density Is Too High

Development is evolving from writing highly readable code to writing highly readable documentation. But most AIs are trained to talk in jargon — possibly to save tokens — squeezing what could be a clear, well-organized paragraph down to two or three sentences that only experts can decode after staring at them for a while. That’s not good.

Of course, most of these flaws aren’t unique to AI. Human-written docs have them too.

So how do we fix it?

2 · The Solution: Borrow the Rules from Aircraft Maintenance

Go find the industry most afraid of being misread. Who is most afraid of readers misunderstanding? Aircraft maintenance.

The readers of maintenance manuals are people who follow the manual with their hands. Misread one sentence, and you take the wrong step.

ASD-STE100, Simplified Technical English (STE), originated in aviation maintenance documentation. It uses a controlled vocabulary and writing rules to help readers accurately understand English technical instructions. Its predecessor, the AECMA Simplified English Guide, was published in 1986. Source: the official ASD-STE100 website.

Put a deployment runbook next to a maintenance manual, and you’ll see they face similar writing problems: the reader must follow the instructions step by step; warnings come before the steps; each step contains only one instruction; conditions are written before the instruction.

STE was written for English. I adapted it for Chinese — the Chinese version has 46 rules across 9 chapters: words, noun phrases, verbs, sentences, operational steps, explanatory text, warnings, punctuation and length, and writing habits. The English version has 49; the 3 extra rules only govern English grammar.

The Chinese rules come in two flavors. 28 are hard rules that must be strictly followed. 18 are soft rules — follow them at least 80% of the time, and any you choose not to follow must be justified in writing. The rule file spells out these requirements, along with reasons, examples, and check methods.

Applying the rules works like swapping parts: find the problematic phrasing, take it off, and install a phrase that can only be read one way.

“Perform compression processing on the logs” — strip out “perform” and “processing,” and you’re left with “compress the logs.” “Clean up the cache at the appropriate time” — this must be replaced with an already-confirmed trigger condition. “It is responsible for retries” — this must be replaced with the name of the component that actually handles retries.

The image above is a constructed example: we’ve already confirmed that “the cache must be cleared after config file changes,” and we’ve already confirmed that Pool handles retries — only then can we make that edit. If neither the original text nor the project materials make these clear, the skill should list the open questions for the author, and must not invent behavior for the system just to make the sentence complete.

The 46 rules can be handed to an agent to consult one by one, with the results then checked by script and by human judgment. Once the rules are written down, execution has a common basis.

In day-to-day writing, you don’t necessarily need to memorize all 46 rule numbers. What’s more useful is remembering the tradeoffs behind them. So I compressed the aesthetic behind these rules into ten sentences, in a style that pays homage to the Zen of Python.

• Complexity over obscurity. Keep every condition, exception, and risk; drop every obscure word.

• Explicit over implicit. Write down who is doing it; if the subject changes, say so.

• Names over pronouns. When “it” could refer to two different things, write the name.

• One thing, one name. Configuration is called configuration — don’t also call it “settings” and “parameters” unless the context requires it.

• Verbs over nouns. Write “compress the logs,” not “perform compression processing on the logs.”

• Specific over vague. Write the number, name, or condition; if you can’t, delete the adjective.

• Flat over nested. At most two “的”-type modifiers before a single noun.

• Say what to do, then why. Conditions before instructions; warnings before steps.

• When facing gaps, refuse to fabricate. Don’t invent numbers; list missing evidence for the author.

• Rules over feelings, practical over pure. Hard rules must be followed; soft rules at 80%, and any exceptions must be justified.

These ten sentences are a memorable summary. For specific problems, the full hai-simplified-technical rule set takes precedence. The eighth sentence especially needs to be read in context: warnings come before the instructions they protect; operational preconditions go before the instruction; the rationale for a whole group of steps can go before the step list.

The sentence I most want to lead with: Complexity over obscurity.

Many people think “simplifying” means shortening sentences. In fact, what this rule set deletes isn’t complexity — it’s obscurity.

Conditions, exceptions, risks, uncertain points — not one may be dropped. Deleting a warning to make a sentence shorter is vandalism, not simplification. What should be deleted is the outer wrapper: packaging verbs, empty intensifiers, and ambiguous pronouns. Good technical documentation reduces unnecessary comprehension while reading — you finish it and can act on it right away, and it’s easy to navigate.

Meanwhile, the content itself can be complex, because reality is complex — but the wording must never be obscure.

Combining STE with my own development experience, I wrote hai-simplified-technical

https://github.com/hylarucoder/hai-stack/blob/main/skills/hai-simplified-technical/SKILL.zh_CN.md

hai-simplified-technical includes a skill description, Chinese and English rule files, a check script, and delivery templates. Once an agent loads the skill, it writes or revises technical docs in five steps:

• Determine scope: confirm this is technical documentation.

• Find project conventions: look for a glossary and style guide first. Where project conventions and the rules conflict, the project wins.

• Write or revise: fix the phrasing per the rules, leaving facts, conditions, and risks untouched.

• Mechanical check: run check.py.

• Deliver: hand over the doc with a summary of changes and check results; any evidence, risks, or content gaps that need the author’s confirmation are listed separately.

There are two design decisions behind this.

First, check.py only points out places worth looking — it doesn’t judge for you. Quoted examples, notations placed right next to code names, and soft rules with a valid justification may all be left as they are. Conversely, a script that reports no errors does not mean pronoun references are resolved, facts are verified, and all rules are satisfied.

Second, missing evidence goes into the delivery notes, not into the body of the text. If the original text says “performance also saw a significant improvement” without any numbers, the skill only removes the word “significant” — it does not insert a “[to be filled]” into the body, let alone invent a number. Only when the reader cannot act without that information should it be flagged in the body. Other data-missing claims are listed for the author in the delivery notes.

That’s the ninth sentence: when facing gaps, refuse to fabricate.

Boundaries: It Doesn’t Write Marketing Copy

This rule set governs technical documentation only: design docs, READMEs, API docs, runbooks, migration guides, PR descriptions, code comments, and error messages.

Marketing copy, release posts, and speeches are out of scope. That kind of writing persuades through rhythm, emotion, and rhetoric — apply these rules and it becomes dry and lifeless. For hybrid documents like release notes, only the technical part gets revised: what changed, how to upgrade, where there are breaking changes.

Technical documentation first makes sure you read things correctly. An introduction article still needs to make you want to keep reading.

So this article keeps its metaphors and rhythm. It introduces the rules — it doesn’t rewrite the entire article as a technical operations manual.

3 · The Results

I recently built a personal video editor. After getting pounded by opus 5.5 / astra 6 / grok 4.7 back to back, the documentation had become quite painful to read — and to solve some fine-grained issues, you have to read the docs more in order to drive the agent forward. After using this skill, the reading experience is dramatically better.

Here’s the comparison.

How do you use it? Just copy this address and paste it into your coding agent:

Install this skill https://github.com/hylarucoder/hai-stack/blob/main/skills/hai-simplified-technical/SKILL.zh_CN.md, then review the xxx-related docs for me and tighten up the wording.

I highly recommend giving it a try. If you find it helpful, please like and share — much appreciated!

References

• The origins of STE: the official ASD-STE100 website

• The Zen of Python: PEP 20 – The Zen of Python

• github.com/hylarucoder/hai-stack