Technical Writer 如何 Review 技术文档？

Foreword

如果你是一个 Technical Writer (TW)，早晚会遇到 Review 技术文档的情况。当然，你写完一篇文档之后，可以自己先 Review 一遍，但本文说的 Review 主要指 Review 他人的技术文档。

技术文档的 Reviewer 通常具备较多的技术写作经验，深谙技术文档规范，语言功底比较好。有时，也会有 Peer Review，比如 Team 小伙伴之间互相 Review。

需要说明的是，大公司和创业公司在 Technical Writer 和技术文档方面有一些区别。使用的标记语言或技术写作工具不同，Review 时关注的点也会有差异，例如使用 DITA (XML) 与使用 Markdown 写出来的文档。

但是，Review 的本质是一样的。Reviewer 具备了相应的经验、能力和意识，无论何种类型的技术文档，均可以应对自如。笔者的分享是基于使用 GitHub + Markdown 这种写作模式一年多的体验，以及曾经使用 Arbortext 一年的经历。

那么，Review 他人的技术文档时，究竟需要 Review 些什么，又有哪些需要注意的地方呢？

本文结构如下：

• Review 相关的行业背景解析
• Review Rule 1：注重细节
• Review Rule 2：全局思考

Review 相关背景解析

先看 Technical Writer，一般在大公司尤其是大外企里，会有专职的 Reviewer/Editor 来审阅 Technical Writer 撰写的技术文档。但是对于中小团队的公司或创业公司来讲，从技术文档的撰写、编辑，到 Review、发布，很多情况下都是由 Technical Writer 这个角色来完成的。

有时，大公司里的 Technical Writer 就像是流程中专门负责某一个环节的角色，而创业公司的 Technical Writer 可能要一个人像一个队伍一样，参与整个流程。当然，也会遵循我之前分享过的完整的技术写作流程。

再看技术文档，大公司里有充足的文档人员配置和完善的流程，通常文档的更新都是由文档团队来完成。而在快速发展的创业公司里，人员配置相对紧凑，文档更新流程极为敏捷，文档的更新从执行者来看可以分为两种：一种是 Technical Writer 提交的，另一种是非 Technical Writer 提交的。

你可能会纳闷了，为什么还有非 Technical Writer 提交的文档呢？

因为与大公司相比，创业公司里 Technical Writer 人员配置相对紧缺，有好几个读者曾给我留言说，TA 刚换到一家新的公司，当时公司做文档的就只有 TA 自己一个人。

如果时间紧迫或内容技术性特别强，开发或运维人员就可能会直接提交技术文档，而不是先给 Technical Writer 提供资料，再让 TW 来修改撰写。这类文档主要是中文文档，英文文档主要还是由 Technical Writer 来撰写或者根据中文文档进行技术翻译。

那么，在 Review 环节，Technical Writer 撰写的文档和非 Technical Writer 撰写的文档有什么区别吗？

• 从 Reviewer 的角度来看，可以说没什么区别。因为都需要用标准的技术文档规范去要求一篇文档，无论这篇文档出自谁，当它呈现给读者时，都应该是规范、易用的。

• 从被 Review 的文档来看，有一些区别。因为术业有专攻，Technical Writer 撰写的文档比较符合技术文档规范，这也是对 Technical Writer 的基本要求之一。相对来讲，非 Technical Writer 的小伙伴可能不了解或不熟悉技术文档规范具体是怎样的，撰写的文档相对不那么规范，因此 Review 时需要调整的地方也相对较多。

Rule 1：注重细节

Pay attention to Details.

如果你是一个注重细节，对细节特别敏感的人，甚至稍微有点儿“细节控”，那么，通常会认为你比较适合做 Technical Writer。

这是因为，一篇规范的技术文档有很多细节方面的要求，如果你本身是一个粗枝大叶、不屑关注小细节的人，那就不大适合做 Technical Writer，做 Technical Writer 的话简直是在惩罚自己了。

对于 Review 技术文档来说，细节很重要，因为它直接影响着一篇文档最基本的呈现质量，影响着用户对产品的使用体验和印象。

在 Review 一篇技术文档时，至少需要关注以下细节：

• 语言
  • 语法是否有误
  • 用词是否规范
  • 逻辑是否恰当完整
  • 表述是否简洁易懂
• 标点
  • 是否误用
  • 是否漏用
  • 是否中英标点混用
• 空格
  • 是否多余
  • 是否缺少
• 缩进
  • 是否规范有效
    • 无序列表
    • 有序列表
    • 次级列表
• 链接
  • 是否有效
  • 相对路径
  • 绝对路径
• 图片
  • 是否正常显示
  • 是否需要文字说明
  • 文字说明的对齐

需要注意的是，细节固然重要，但也不要陷于细节无法自拔，有时需要根据当下的实际需求与人力、时间资源等因素做出权衡。

Rule 2：全局思考

See the Whole Picture.

在 Review 技术文档时，除了需要注意细节，还要注意全局思考，从整体上审视和把握文档的结构和组织是否得当、是否可以更好，将微观与宏观相结合。

从整体上可以关注以下几点：

• 正文内容是否与标题相符
• 结构上是否符合逻辑
• 结构上是否清晰明确、用户友好
• 结构上是否缺失必要的内容
• 结构上是否存在赘余
• 某部分正文是否可重新组织以更易用

Afterword

对于一篇技术文档来说，在正式发布之前，Review 是规范的流程里必不可少的一个环节。

在实际工作中，Review 一篇技术文档，有时只需要几分钟或十几分钟，有时则需要半小时甚至更长，视具体情况而定。

不管做什么，都需要把握一个度。Review 技术文档也一样，既要注重细节，也要有全局观，从整体上进行 Critical Thinking。

你可能想读：

技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
如何使用颜色来提高技术文档的可读性？
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
英语技术文档的标题到底该大写还是小写？
如何使用正则表达式批量添加和删除字符？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记

-END-