Why Documentation Always Comes Last — and How AI Fixes That

Foreword: Why Documentation Always Gets Written at the Last Minute

Independent developers and small teams are all too familiar with this: the APIs are written, the features work, but the documentation is still empty. It's only when you need to integrate with collaborators, list on an open platform, or deliver to a client that you scramble to fill it in. Even worse is the error code documentation — hundreds of error codes scattered throughout the codebase. Which ones are still in use, which ones are deprecated, and what message each code should return? Nobody can say for sure.

I recently organized the API documentation for a medium-sized project. A rough count: about 40 endpoints and over 120 error codes. With the old approach — pure manual work — this would take at least two full days. This time I handed the whole process to AI, and from data extraction to final draft, it took less than forty minutes — not counting the two cups of coffee I had in between. This article is a retrospective of the entire process, with a focus on one thing: what exactly the AI did for you at each step.

User Pain Points: Three Deadlocks of Documentation Debt

First, information is scattered. Error codes might be defined in enum classes, constant files, or even hardcoded directly in logic branches. Verifying them one by one manually is time-consuming and prone to omissions.

Second, the writing burden is asymmetric. Writing code feels rewarding; writing documentation doesn't. For the same endpoint, implementation takes half an hour, but clearly documenting parameter descriptions, call examples, and exception scenarios can take an hour.

Third, updates always lag behind. The endpoint has been modified three times, but the documentation is still on version one. When an integration partner comes asking questions with outdated docs, you have to spend time explaining all over again.

The common essence of these three points: documentation is highly repetitive, low-creativity work — exactly the type of task AI is best at taking over.

The AI Workflow: Four Steps

Step 1: Let AI Collect, Not Guess

First, feed the relevant source code to the AI: error code enums, route definitions, and controller code. The key instruction is "extract only, do not infer." The AI will list all error codes, trigger locations, and corresponding exception types within tens of seconds. This step replaces manual code review — previously two hours of work.

Step 2: Let AI Cross-Validate

Provide the AI with both the API registration documents (e.g., OpenAPI/Swagger-exported JSON) and the code, and have it compare the differences: "Which endpoints exist in the code but are missing from the documentation," and "In which endpoints is each error code actually returned." It can catch those zombie endpoints you've long forgotten about. Doing this comparison manually drains enormous patience; with AI, you get results in one minute.

Step 3: Batch-Generate Descriptions from a Template

This is the core efficiency-boosting step. Give the AI a fixed description template and have it output a consistent structure for each error code: error code, meaning, trigger scenario, user-facing message suggestions, and troubleshooting directions. Once the template is fixed, descriptions for 120 error codes are generated in one pass.

Step 4: Manual Spot-Check to Wrap Up

AI-generated content must be spot-checked, especially whether the trigger scenario descriptions match the actual logic. This time I spot-checked about 20% of entries and found three description discrepancies — fixing them was just a matter of tweaking the prompt and regenerating the corresponding entries. This step cannot be skipped — documentation is meant for others to read, and one wrong statement damages trust more than one omission.

Prompt Template

Here is the template I've refined, ready to copy and use:

你是一名API文档工程师。我会提供【错误码定义源码】和【接口代码】两部分内容。

请完成以下任务：

1. 提取所有错误码，输出字段：错误码 / 常量名 / 所在文件与行号 / 触发逻辑（引用代码原文）
2. 对每个错误码，按以下模板撰写说明：
   - 错误码：{{code}}
   - 含义：一句话
   - 触发场景：从代码逻辑推导，注明依据
   - 客户端处理建议：一句话
   - 排查方向：1-3条，面向后端开发者
3. 规则：
   - 只基于提供的代码，不确定的信息标注[待确认]，禁止编造
   - 同一错误码在多个接口出现时，合并触发场景
   - 输出为Markdown表格，附在文末
4. 最后单独列出：代码中定义但从未被返回的错误码（疑似废弃）

The value of this template lies in two rules: "no fabrication" and "mark as [to be confirmed]" — these are what make AI output directly usable, rather than something that needs to be rewritten line by line.

Before and After Using AI

Converted at two work days, that's about 13 hours saved per run. For a three-person team maintaining documentation with every release, the annual time savings are measured in "weeks," not "days." The more important hidden benefit: once documentation maintenance costs drop low enough, the docs can actually stay up to date — and that's what fundamentally improves the integration experience.

As for cost, processing this volume of input and output with a mainstream large model typically costs less than a cup of coffee per run — check the official pricing page for specifics. Even if you use a more expensive reasoning model throughout, the return on investment is wildly disproportionate.

Three Practical Tips

1. Feed in batches. When the codebase is large, split it by module first to avoid missing items due to context overflow.
2. Version your prompts. The template itself should go into Git, with every tweak recorded, so the whole team shares one standard.
3. AI writes the draft, humans set the tone. The wording of the "meaning" column should be unified manually, since it faces the integration partner directly, and stylistic consistency affects perceived professionalism.

Final Thoughts

The reason we've been in documentation debt isn't laziness — it's that the output per unit of time was too low. When AI pushes that cost down to less than a tenth of what it was, "no time to write documentation" is no longer an excuse. If your project involves external API calls, model service integration, or third-party endpoint integration, run this workflow once — the payoff is immediate.

If you're building or integrating AI-related services and need a stable model invocation gateway, check out this platform — register and start experimenting with API access to various models: https://api.thistoken.ai/register

---

Ready to try it yourself? Sign up at https://api.thistoken.ai/register to get your API key and start building.