A widely-circulated developer post on Juejin (掘金) makes one central claim: the most common failure when using AI to write tech docs isn't that it can't write — it's that it produces lengthy, fabricated content: rewriting code comments into paragraphs, padding with empty phrases like "the system improves efficiency," and even passing off AI-guessed content as project fact.
The author's fix is a "two-step separation" workflow: first, let AI only extract facts; then, let it organize language. After the draft, a human checks five items — most critically, "does the example actually run." The value of this pipeline isn't in how cleverly AI is used, but in forcibly splitting judgment from expression.
What this is
We've noticed a recent surge in articles of this "AI tool usage experience" type, with the theme: when AI is used to write API documentation, how to avoid producing "long and unusable" content. This article's methodology can be broken into three layers.
The first layer is pre-writing boundary-setting: answer who the reader is, what task they need to complete, what must be included, what must be excluded — this determines AI's output direction.
The second layer is a fixed doc structure: feature description, prerequisites, invocation method, return results, error handling, complete example — six sections, delete what doesn't apply, don't pad for the sake of completeness.
The third layer is separating "fact extraction" from "organizing expression": first let AI extract verified facts from the code, then write those facts into docs; mark unconfirmed items as "to be confirmed" and prohibit AI from filling them in.
The author also provides a 5-item human checklist: do the examples actually run, are parameters consistent, do return fields really exist, have error codes been confirmed by the project, has unverified content crept in.
Industry view
The fact that this post is widely saved tells us it struck a universal pain point — many teams see "output volume" rise after adopting AI writing tools, but "usable output" doesn't necessarily follow. The core insight: AI is strong at structure and expression, weak at judging factual truth. Workflows must isolate the judgment step.
But counter-arguments deserve attention. A senior engineering manager points out that the two-step method only works if someone on the team can read code and verify examples; if the doc writer doesn't understand the tech, this workflow actually backfires — producing a "looks professional" facade that masks errors. Additionally, the author's method depends heavily on individual prompting habits and hasn't been codified into reusable team standards; it works for API docs, but won't necessarily transfer to requirement or design docs. Workflows must be customized by scenario.
Impact on regular people
For enterprise IT: when adopting AI writing tools, don't just measure "how many characters saved" — measure "how many characters are directly usable." Otherwise you're just manufacturing content waste that requires rework.
For individual careers: AI is good for structured first drafts, but fact-checking and business judgment must remain human work — the "human review" step in the workflow isn't optional.
For the consumer market: the next competitive frontier for AI writing products isn't model capability — it's whether vendors can ship workflow templates like "extract — organize — verify," which is what everyday users actually lack.