A Manager's Age-Old Problem: Documentation Never Keeps Up with Tools

Anyone who has led a small team knows this scene all too well: a new colleague joins, you hand them a CLI tool doc, and three days later they're still asking in the group chat, "What does this command's parameter mean?" The old documentation was written two years ago, and the tool has gone through a dozen-plus versions since; the command help output keeps growing, with --help filling two full screens that nobody reads through; and the Wiki notes are all over the place—some outdated, some just one person's personal writing habits.

My team maintains several CLI tools that mix in-house development with open source. Our old way of handling this problem was to designate someone as "responsible for documentation." The result: that person was always busy with something else, and doc updates never made it into the iteration plan. It wasn't until an online incident—when a new hire used a deprecated parameter and wiped out the test environment data—that I resolved to turn the "user manual" into a proper process. And the role AI plays in this goes far beyond "helping me write a few paragraphs."

First, Let's Be Clear: What Can AI Actually Do Here

From a manager's perspective, AI-assisted manual writing isn't about having AI generate a complete document in one shot. It's about having it take on specific work across four stages:

1. Information gathering: consolidating scattered sources

Feed the --help output, README, changelog, FAQ records from group chats, and even historical ticket descriptions to AI, and let it categorize and organize: which are core commands, which are obscure parameters, and which are legacy leftovers already deprecated. This step used to take a person a day or two of manual work; AI produces a structured first draft in minutes.

2. Structure design: layering by user role

A good manual isn't an exhaustive command reference—it's layered. AI can generate three paths of different depths based on team roles (newcomers / daily users / admins): newcomers only need "five commands to get through the main workflow," while only admins need configuration and permissions content.

3. Content generation: examples matter more than parameter tables

The tool itself outputs parameter tables; what people actually lack is "I want to do X—how do I combine the commands?" Have AI generate scenario-based examples from the command definitions, annotating each example's prerequisites and risk points.

4. Review: the critical line of defense for risk control

This is the step managers should pay the most attention to. Have AI run a dedicated "dangerous command review": flag every command involving deletion, overwriting, write operations, or environment state changes, and mandate warning labels and rollback instructions in the documentation. The incident mentioned above was, at its core, a failure of exactly this layer.

What Our Process Looks Like

The implemented process has five steps, each with clear deliverables and an owner, avoiding the common pitfall of "nobody vouches for what AI wrote":

1. Collect: The owner gathers the tool's --help, README, changelog, and FAQ into a single directory.
2. AI organizes: Use a prompt template (see below) to generate a layered first draft of the manual.
3. Human review: The tool's maintainer verifies command by command that commands and parameters are still valid, with special focus on whether AI-generated examples actually run.
4. Risk annotation: AI performs the dangerous-operation review; a human confirms the warning labels and supplements rollback plans.
5. Version binding: The manual version is bound to the tool version. Every time a tool upgrade changes the changelog, feed the diff to AI for an incremental update, then run a quick review pass.

The key to this process is: AI handles the grunt work and coverage; humans handle accuracy and sign-off. There are only two risks a manager needs to control—misleading documentation for newcomers, and dangerous commands without warnings. Steps 3 and 4 of the process exist specifically to plug those two holes.

A Reusable Prompt Template

Here's the core prompt template we use in step 2—just replace the bracketed content:

你是一名资深技术文档工程师。请基于我提供的材料，为 CLI 工具「[工具名] v[版本号]」编写一份分层使用手册。

【材料】
1. --help 完整输出：[粘贴]
2. README / changelog：[粘贴或粘贴链接内容]
3. 团队常见问题记录：[粘贴]

【输出要求】
一、按三类读者分层组织：
   - 新人上手：5 个以内命令走通主流程，每步附完整示例和预期输出
   - 日常使用：按任务场景组织（如"批量处理""查询""导出"），而非按字母序
   - 管理员：配置、权限、环境变量说明
二、每个示例命令前标注：适用前提、是否有写操作、出错时如何回滚
三、单独列出一节「危险命令清单」：凡涉及删除、覆盖、批量修改的命令，
   用 ⚠️ 标注并说明典型误用场景
四、列出你在整理过程中发现的：材料之间互相矛盾的地方、疑似已废弃
   但未声明的参数。不要自行猜测，标记为"待人工确认"
五、语言风格：短句、命令可复制执行、避免营销化描述

Point 4 deserves special emphasis—having AI proactively surface "uncertainty" instead of glossing over contradictions is the most practical technique for controlling documentation quality risk.

Before and After AI

The most visible change is a clear drop in "how do I use this command" questions in the group chat—not because everyone suddenly loves reading documentation, but because the docs are finally organized around "what people want to accomplish" rather than "what parameters the tool has."

A Few Managerial Reminders

• AI-generated ≠ publishable. Example commands must be run in a real environment before entering the manual. This step cannot be skipped, or the manual itself becomes a source of risk.
• Don't chase the perfect manual in one shot. AI's strength is low-cost rewriting. Keeping documentation "good enough and fresh" matters far more than making it comprehensive.
• Treat the prompt template as a team asset too. Store the template in the repository—whoever maintains it uses it. This prevents the process from regressing into an individual skill.

The biggest insight this gave me: AI's value in documentation isn't "writing fast"—it's turning "maintaining documentation" from a burden nobody wants into a process cheap enough to embed in daily iterations. Only when the cost is low enough does the work actually keep happening.

If your team is also using multiple model APIs for this kind of automated workflow, check out Thistoken's unified access service—one interface connecting to multiple model providers, making management much easier. Register here: https://api.thistoken.ai/register

---

Every example in this post runs with a single API key — get yours at https://api.thistoken.ai/register and start in minutes.