写作
标签文章: 写作
API
减少支持工单的认证文档
围绕“减少支持工单的认证文档”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“减少支持工单的认证文档”，重点是可执行、可验证和可维护的做法。
2 分钟阅读
学习
2026 年技术写作者该读什么：持续更新的指南与仍然有用的书
真正有用的阅读清单不再只是经典书目。把 Microsoft、Google、GitHub、IBM 的现行指南放在一起比较，用 Diátaxis 检查内容结构，并把每次阅读变成一次真实的文档练习。
5 分钟阅读
学习
技术写作者的刻意练习：训练真实工作，而不是流行词
阅读文档理论有帮助，但能力增长更快的方式，是反复完成小型调研、重构、编辑和验证练习，并获得明确反馈。 “提高技术写作能力”太宽泛。一次只练一个能力：减少歧义、设计 procedure、采访 engineer、编辑 API example、重构导航或建立术语表。
2 分钟阅读
工具
图表即代码：什么时候有用，什么时候没有
围绕“图表即代码：什么时候有用，什么时候没有”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“图表即代码：什么时候有用，什么时候没有”，重点是可执行、可验证和可维护的做法。
3 分钟阅读
API
如何记录 API 错误，让开发者能够恢复
围绕“如何记录 API 错误，让开发者能够恢复”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“如何记录 API 错误，让开发者能够恢复”，重点是可执行、可验证和可维护的做法。
3 分钟阅读
API
如何正确编写 REST API 文档
好的 API 文档需要把机器可读契约、人类解释、可运行示例和明确的错误行为结合起来。 REST API 文档同时面向机器和人。机器可读契约描述 path、method、parameter、schema 与 response；人类文档解释意图、约束、工作流和开发者要做的选择。
2 分钟阅读
学习
提升技术写作的编辑练习
围绕“提升技术写作的编辑练习”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“提升技术写作的编辑练习”，重点是可执行、可验证和可维护的做法。
3 分钟阅读
工具
大规模 Markdown：避免仓库失控的约定
围绕“大规模 Markdown：避免仓库失控的约定”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“大规模 Markdown：避免仓库失控的约定”，重点是可执行、可验证和可维护的做法。
3 分钟阅读
API
OpenAPI 是事实来源，但不是完整的 API 文档
OpenAPI 描述可以生成准确的 reference 结构，但开发者仍需要概念、任务流程、身份认证、示例和错误恢复，这些不是一个 schema 能单独解释的。 OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。
2 分钟阅读
实践
让用户知道该做什么的发布说明
围绕“让用户知道该做什么的发布说明”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“让用户知道该做什么的发布说明”，重点是可执行、可验证和可维护的做法。
3 分钟阅读