技术写作

技术写作的目标是让特定读者安全、准确地完成任务或理解系统。自然表达固然重要，但不能以改动命令、参数、代码或执行顺序为代价。一个句子读起来更顺，如果导致读者使用错误端点或跳过备份步骤，仍然是失败的修改。

开始前定义读者、环境和结果。新用户快速开始、经验丰富的运维手册和架构决策记录需要不同背景。说明支持的操作系统、版本、权限和依赖，避免把仅在作者机器上成立的条件写成普遍事实。

围绕任务组织内容

操作指南应先说明完成后会得到什么，再列出前置条件和有序步骤。概念说明则应先建立系统边界和关键术语，再解释组件关系。不要在同一段中混合背景、命令和故障处理。

每个步骤包含一个主要动作，并说明必要输入和可观察结果。顺序不可交换时使用编号；可选项目可用列表。不要把失败条件藏在步骤之后，尤其是会覆盖、删除或公开数据的操作。

标题应描述读者任务，如“配置访问令牌”或“恢复失败的迁移”，而不是宽泛的“配置事项”。可扫描结构帮助读者在压力下找到正确位置。

代码块、命令、路径、环境变量、API 字段、状态码和版本号应锁定，除非任务明确要求修改它们。普通语言编辑不能更正看似奇怪的大小写，也不能把连字符改成下划线。

行内标识符使用代码格式，并与真实界面或接口保持一致。示例值应明显区分于真实秘密；永远不要把 API 密钥、令牌或凭据放进公共文档、模型提示或日志。

修改后应实际运行可运行的示例，或由自动测试验证。仅凭阅读无法证明命令仍然有效。

技术句子应回答动作在什么条件下发生、成功如何判断、失败会看到什么。“重新启动服务”不如“保存配置后重新启动服务，并确认健康端点返回 HTTP 200”可验证。

不能发明工具没有证据的输出。日志样例应来自经过脱敏的真实结果或明确标注的示意内容。说明版本差异时给出适用范围，避免把未来计划写成当前能力。

危险操作需要在执行前给出明显警告，包括受影响对象、是否可恢复和备份要求。不要用笼统“请谨慎”代替具体影响。

为目标读者保留必要术语，并在首次出现时给出简洁定义。不要为了“简单”把具有精确含义的认证、授权、加密或缓存概念混为一谈。普通词无法保留区别时，术语比近义替换更安全。

缩写首次出现时展开，除非读者普遍熟悉。一个概念使用一个名称；随意变化会让读者怀疑是否指不同对象。

图表和示例应支持正文中的任务。替代文本要传达图像中完成任务所需的信息，不能只写“截图”。

修改前：“在进行了相关配置文件修改之后，用户应该可以考虑执行一下服务重启操作，以便相关变更能够得到应用。”

修改后：“保存配置文件，然后重新启动服务以应用更改。”

第二版更直接，但只有当保存和重启确实足够时才准确。若还需迁移数据库、重新加载代理或等待任务完成，必须保留这些步骤。不能为了简洁删除前置条件。

从干净环境按文档操作，核对每条命令、路径、参数、版本和预期输出。测试失败路径与恢复步骤，检查链接和权限说明。让不熟悉实现但属于目标读者的人尝试任务，记录他在哪里需要猜测。

再进行安全审阅：确认没有秘密、内部地址、个人数据或不必要的权限要求。检查破坏性步骤是否清楚说明范围和恢复方式。

THumanizer 可以改善说明文字的清晰度与结构，但不应改写代码或验证系统行为。技术作者仍需以实际接口、测试结果和安全要求为依据发布文档。