Foreword

我在日常工作中 Review 小伙伴们新提交的数据库用户文档时，会时不时地发现一些理解问题。这里的“理解问题”包括：理解不到位、解读不确切、没有挖出对用户易用友好的信息，甚至出现理解错误等等。

那么，为什么会出现这种理解问题？又该如何避免这种理解问题呢？

之前跟大家分享过一篇《技术写作实例解析 | 若脱离理解，直译得再正确又有何意？》，举了两个实际工作中遇到的例子，直观地呈现了 Technical Writer 在处理技术文档时，理解内容与「发挥主观能动性」的重要性。

在《技术文档翻译实例解析 | 始于翻译，经于沟通，终于易用》中，也分享了用户文档中某一句话跌宕起伏、历经波折的诞生记。在那一个例子中，与工程师的沟通是 Technical Writer 理解内容、正确地呈现内容的前提。

上述两篇文章谈的是正确理解技术内容的必要性，以及正确理解技术内容的一些方法。那如果没能正确理解呢？自然就很容易出现理解问题了……

这一篇呢，会从相对宏观的角度出发，聊聊为何会有理解问题，以及如何避免。当然，有些产品本身比较简单，一看就懂，或许不会或极少出现理解问题。

本文结构如下：

• 为什么会有理解问题
• 如何避免理解问题

为什么会有理解问题

对于 Technical Writer 来说，无论是搜集材料自己来写技术文档，还是翻译技术文档，源材料或源文本的语言质量是不好控制的。这些内容有的来自研发工程师，有的来自数据库管理员，有的来自产品经理，有的来自社区同学等等。

虽然理想情况下，翻译的文本内容最好都是自己能理解能读懂的。但是，现实情况往往会有一些出入。那么，在内容来源相对不可控的情况下，如果稍不留神，便很容易产生理解问题。

以处理数据库的用户文档为例，Technical Writer 在翻译或写作技术文档时，遇到理解问题可能有客观原因和主观原因。

客观原因：

• Technical Writer 的技术和产品知识储备不足，但无法像相关的技术同学一样掌握所有细节。

  从 Technical Writer 的角度来看，可以学习掌握一些数据库的基础知识和产品知识，但不可能掌握和理解所有技术细节。有些技术细节甚至只有负责这块的同学才比较清楚，即便其它技术团队的工程师也不一定知晓细节。这种情况下，Technical Writer 在准备用户文档时很可能会遇到理解问题。

• 软件工程师等技术同学提供的源文本或源材料表述不清晰，但无法像 Technical Writer 一样写得特别规范。

  从工程师等技术同学的角度来看，他们提供的源文本在语言表述上往往不是那么正式和规范。或许 TA 自己觉得能看懂，以及 TA 所在团队的同学能看懂，但其他人无法明确知道在说啥，尤其是技术背景相对比较薄弱的 Technical Writer。

主观原因：

这里主要从 Technical Writer 的角度来看：

• 粗心、不细致、不认真，本来稍加分析思考就能理解正确的内容，却理解错了。

• 懒惰心理作祟，嫌麻烦，不理解的内容也不与技术同学沟通，本来沟通可解决的问题，却置之不理。

• 侥幸心理作祟，觉得应该是自己理解的那个意思吧，虽然不能百分之百确定，应该问题不大。这种「碰运气」似的处理方式，长此以往，定会影响文档质量。

如何避免理解问题

设想一下：如果 Technical Writer 和软件工程师这两种角色能无限趋近融合，是不是就完美了？

即 Technical Writer 可以写代码看懂代码，软件工程师通晓各种写作规则与规范，可以写出逻辑清晰、表述规范的文档。如此，理解问题就能在很大程度上避免了。

然而，大多数情况下，这种设想还是不太现实……

当然，也有一些软件工程师转行做 Technical Writer 的例子。这样的话，或许能逐渐达到所设想的理想状态。好奇这是怎样一种职业转换的小伙伴可以看一下这篇文章 My Journey From Developer to Technical Writer。

不过，很多软件工程师不喜欢写文档，转行做 Technical Writer 不是那么普遍。对我们当前工作中遇到的实际问题，这种职业转换的例子也并不算一种解决方案。

那么，在力所能及的范围内，我们怎么做可以尽量避免内容理解问题呢？

客观方面：

• Technical Writer 积极地、不断地学习相关行业的技术知识与产品知识，充分利用组织内外现有的各种学习资源。

  是的，学无止境。Technical Writer 要提高自己的技术与产品知识积累，就必须不断学习。此外，关注行业同类产品的发展动态与各种内容输出，可用于参考或辅助理解。

  在有了一定的知识积累后，你会逐渐发现，即便源文本表述不规范、不清晰，你也能理解作者想表达的意思，并可以正确地重新组织为易用的用户文档。

  当然，依然会有无论你怎么解读都无法 Get 到意思的情况，也很正常，因为有时你去问原作者，他自己可能也不清楚自己想表达啥了，或者自己也不能完全确定技术内容的正确性。此时，可能要去请教其他的技术同学了。

• 软件工程师等技术同学熟悉用户文档的风格与规范，提高自己书面表达的逻辑，尽量让自己写出的内容逻辑清晰、表述规范。

  这一点对平时写代码的同学来说，或许就像 Technical Writer 学技术知识的感觉一样，要做好可能有点儿难。但提高写作能力对程序员本身也是一件颇有益处的事情，可以减少 Technical Writer 来找自己沟通确认内容理解问题的时间，还可以自己撰写一些高质量的技术博客类文章，经过 Review 和编辑后发布在公司官方博客上，或者发到自己个人的技术博客上，对自己也是一种积累与提升。

主观方面：

Technical Writer 要做到以下几点：

• 要细心再细心，在工作实践中不断提高自己对内容错误的敏感度，培养敏锐的错误分析能力。很多时候，结合上下文与产品常识，简单地加以分析，多一些思考，就能避免不少理解问题。

• 对待工作要认真，要积极主动地应对，对于自己不理解的内容，可先自己搜索，然后找到相关同学沟通确认，这是做文档工作最基本的一种严谨。虽然有时「懒惰」也是一种很有用的东西，可以让你去思考更好的或自动化的解决方案，但与这里谈的“懒惰”有别，在态度上还是要尽量避免。

• 杜绝侥幸心理，对于不能百分之百确定自己理解正确的内容，一定不能糊弄过去，或许有时你理解的是对的，但有时也会是错的，技术文档需要的是确切的内容，切忌提交自以为的内容。

Afterword

对于技术难度较高的产品，Technical Writer 或许常会遇到不能完全理解的情况，此时就需要注意避免将「理解问题」带入发布的用户文档中。对于相对比较容易理解的产品，Technical Writer 也需仔细、认真、细心地对待，避免一些个人疏漏导致的理解错误。

目前，国内的 Technical Writer 分布在诸多行业，有软件，有硬件。不知业内小伙伴们在学习工作的实践中是否也遇到过理解问题？

因行业与产品有别，遇到的问题与处理方式或许也不一样。如果有的话，欢迎留言分享交流哦~

-END-

猜你想读：

什么样的人适合做 Technical Writer？
技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
Write the Docs：连接技术文档人的全球社区，附海量学习资源
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
技术传播人士应该知道的色彩搭配常识
如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
行业动态 | 国内有哪些高校开设了技术传播或技术写作课程？
IEEE ProComm 2019 国际传播大会上，中国代表团有哪些精彩分享？
优质免费资源推荐 | 9 期技术写作短视频教程带你从入门到进阶
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？
Technical Writer 如何参与开源项目的文档，以不断提升专业技能?
技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”
经验分享 | 对用户文档进行伤筋动骨式的重构是怎样一种体验？
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
英语技术文档中如何正确使用无序列表和有序列表？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
技术文档翻译实例解析：始于翻译，经于沟通，终于易用
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
如何利用 GitHub Pages 和 Hugo 轻松搭建个人博客？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记