技术文档改写是否应该删掉全部术语？

不应该。保留会影响操作和理解的关键术语，并用第一次出现时的解释、示例或对照帮助读者进入语境。

图文教程能替代官方文档吗？

不能。图文应帮助读者完成一个具体任务，并链接到官方文档处理完整参数、版本和异常情况。

逐条比对会改变操作的名词、条件与结果，确认关键术语命名一致，并核对示例是否来自真实可访问的文档或测试环境。

图卡狐编辑部2026年7月14日

技术文档改写最容易掉进两个极端：要么把原文逐句翻译，读者还是不知道怎么做；要么把术语全删了，内容看着亲切却没法执行。更好的起点是先定义读者任务——他要安装一个工具、理解一个概念、排查一个错误，还是比较两个方案？任务一旦明确，就能判断哪些信息必须先出现，哪些该链接到官方文档。

比如面向新手解释 API，第一张卡不必讲完所有认证协议，先说清“你把一个请求发到哪、要准备什么、成功后会看到什么”。术语还在，但被放进了动作和结果之间。专业写作里的清晰、准确和一致，是靠稳定的命名和可验证的步骤撑起来的，不是靠口语化堆出来的。

四类任务的卡片结构不同：配置看重前置条件和验证方式，概念看重边界和例子，排查看重现象到原因的路径，比较看重判断标准而不是替读者下结论。Apple 的人机界面写作指南与 GOV.UK 的界面写作规范都强调以读者能完成的任务为中心。

Apollo 的 UX Writing Style Guide 对术语、语气和读者任务的处理可作参考。每一步都要能回答：删掉这句话，读者的操作会不会改变？不会，就该考虑压缩或移走；会，就说明它是必留信息。

写作时可以用“术语（通俗解释）”的双轨表达，比如“令牌（证明请求身份的一段凭据）”，之后统一用“令牌”，别一会儿“密码”一会儿“钥匙”。比喻适合帮读者第一次理解，但替代不了精确概念。同一个对象、同一个按钮、同一条命令，全文只保留一种叫法，读者才不会怀疑是不是两个东西。

还要区分“必须保留的术语”和“可以换成人话的术语”：影响操作、搜索和排错的名词要保留原文，纯装饰性的行话可以删。改写的目标是降低理解成本，不是把专业感一起删掉。

假设原文写的是“调用接口前需完成鉴权并携带有效凭证”。面向新手可以改成三步：先在哪拿到凭证（输入与来源）、把它放进请求的哪个位置（动作）、失败时先看哪类错误信息（验证）。这时术语“鉴权”“凭证”仍然保留，但被放进了任务序列。

涉及版本、参数、价格或安全要求时，以发布当天的官方文档为准，并标注检查日期；本文示例的查阅日期为 2026-09-21，技术细节可能更新，发布前请复核官方页。若示例来自某个具体版本，也应在卡片上写清适用版本，避免读者在别的版本照做出错。

一个常用序列：任务封面、适用条件、全流程地图、步骤一到四、常见错误、结果检查、官方文档入口。每页标题写出动作或判断，比如“先确认版本，再复制命令”，而不是干巴巴的“环境配置”——这会逼作者把抽象章节改成可执行信息。

在图卡狐编辑器里，先为“术语提示”“命令/参数”“风险提醒”建三种视觉样式，别把所有内容都做成同一种正文。需要先调整整篇的优先级，可配合倒金字塔写作方法处理结论和细节的顺序，卡片层级可参考教程图文信息层级。

技术内容可以亲切，但不能含糊。读者愿意保存的，从来不是“看着简单”的卡片，而是需要时真能完成任务的说明。改写结束前，把上面五条逐条过一遍，再决定能不能发布。