说人话.AI

首页 / 指南 / 技术文档去套话

技术文档怎么去套话（别改成闲聊）

README、Release Note、周报、Issue、API/FAQ 最怕两种错：空喊价值，或为了「像人」补假能力/假排期。说人话只清套话，保住命令、版本、限制与责任。

技术文档 AI 味长什么样

  • 发版宣言、赋能闭环、深耕细作、稳稳兜住核心诉求
  • 名词化空转：进行了梳理、实现了下降、开展了优化——却无动作与数字
  • 补原文没有的能力、用户群、排期或「百分之百安全」
  • 为「像人」把准确技术句改成闲聊，术语被口语化误伤

README / 项目简介

首屏三问：是什么？给谁用？解决什么问题？

常踩坑：「赋能开发者」「系统性升级」；原文没有却补上用户群或能力清单。

规则：保留实际用途、适用范围与限制；不自作主张加案例或卖点。

教学示例 · README

坏（空壳）：本工具赋能开发者，系统性升级协作体验，稳稳兜住核心诉求。

说人话有界清理（材料不足）：本工具给开发者用。空壳已删；具体做什么、给谁、限制是什么，要另补材料，不在这里编。

好形态（材料齐时才写得出）：命令行工具：读两份缓存 dump，列出键的增删与值差异。适合排查配置漂移。不替代完整 diff 工具。

教学示例：下面「好形态」不是把空壳句改出来的——没有材料就写短，别为「像人」补假能力。密度参考常见 CLI 说明，非某仓库原文。

Release Note / Changelog

规则：只改已有变更表述；不编版本号、修复项、测试结论、升级命令。

常踩坑：发布宣言、「全面优化体验」「能力矩阵」。

好形态：变更列表；缺 changelog 时不编数据。可先用「只标问题」审一版 RN。

周报 / 开发同步

常踩坑：「进行了梳理，实现了下降，开展了优化」；无数字却写「显著提升」。

规则：还原为直接动词；保留已有数字与时间归属；没有的指标不补。

教学示例 · 周报

坏：对部署流程进行了梳理，实现了发布耗时的下降。

好：梳理了部署流程，发布变快了。

教学示例：若原文无耗时数字，不要编造「从 12 分钟降到 4 分钟」。

Issue / PR 回复

规则：不能补排期、复现结论或要求用户做原文没有的操作。

结构建议：复现理解 → 判断（能否复现 / 是否范围内）→ 下一步（要什么信息或怎么关）。不做客服安抚腔。

可用「只标问题」审别人的模板腔回复。

API 文档与 FAQ

  • FAQ：执行前条件与警告留在操作前；不能为了先给答案挪后；不把事后检查改成前提。
  • API：method、endpoint、参数、返回值、限制按原文保护。

升级 FAQ 里「大家都知道……百分之百安全」要改掉空承诺，保留真实升级路径与限制。

先锁什么再改（力度）

先锁命令、版本号、路径、接口字段、状态码、责任人和「可以 / 可能」等情态，再清套话。别改成闲聊。

场景建议
命令 / 参数密集in-place 或只标问题
有空话段落但结构要留bounded
简介重写且用户授权structural（仍保有效信息）

可复制规则与提示词

技术文档短规则

这是技术文档改稿。先锁命令、版本号、路径、接口字段、状态码、责任人和「可以/可能」等情态，不要改成闲聊。
按文类：README 说清是什么/给谁/解决什么；Release 只列变更与限制；周报只写已有事实，无数字不编；Issue/PR 先复现与下一步，不做客服安抚。
删发版宣言、赋能闭环、深耕细作等空话。术语有技术含义就保留。缺信息就标明要补，不要替我编。

相关：AI改稿保事实 · 套话清单 · 自查清单 · 改过头 · 开源对照

交稿自查

  1. 还空话吗？（发版宣言、赋能闭环、深耕细作）
  2. 编数字了吗？（耗时、百分比、排期原文没有就不要补）
  3. 改成闲聊了吗？（术语、命令、限制还在不在）

常见问题

技术文档能不能写得更口语？

先清楚。硬加「我觉得」往往是改过头——见 去AI味改过头。技术文优先准确，不硬口语。

会不会改掉命令？

默认锁定命令、版本号、路径、接口字段与状态码。只有你明确要求修改时才动这些。

和「降 AI 率」有关吗？

不做。去AI味 ≠ 降AI率，见 立场说明。

相关阅读

规则形态与保守改写边界见 对照说明；本页不写安装。