图片源自 Google 官网
Foreword
"Every engineer is also a writer."
程序员也需要写技术文档吗？是的。
尚未入技术传播这一行的小伙伴可能会理想化地认为：所有技术文档都是 Technical Writer 从头来写的。现实往往复杂得多，尤其是当产品技术性较高时，例如数据库产品。很多时候，程序员是需要写技术文档的，因为有些文档只有研发同学才能产出。
当然，也不排除有些产品的文档 Technical Writer 可以独立完成。这要视产品的具体情况而定，例如撰写一个吹风机的用户文档和准备一个数据库的用户文档，肯定有很大差别。
在我的日常工作中，经常会与研发同学打交道，或是了解某个特性的进展，或是沟通技术细节的正确性，或是彼此 review 文档。这个 review 需求通常是双向的，Technical Writer 需要研发同学 review 技术正确性，研发同学需要 Technical Writer review 语言的正确性与规范性等。
有少数研发同学比较擅长写作，逻辑清晰，表述规范，注重格式等。但毕竟各有所长，大多数的研发同学在写作方面比较薄弱，写出来的文档问题较多，review 成本就比较高。如果研发同学能掌握一些技术文档写作的基本规范和专业知识就好了。
不论你是有意加入技术传播行业的小伙伴，还是已经工作的程序员、计算机专业的在校生，都建议学习掌握一些基本的技术文档写作技能，会在工作中帮到自己。
正好，Google 推出了面向工程师的技术写作课程，内容涵盖了写技术文档时需要掌握的一些基本的专业知识。该课程资源不仅可用于自我学习，还可用于教学或培训，对刚开始教授技术写作课程的高校老师也是一个不错的参考。
特此感谢黄然同学发现这一课程资源后分享给了团队同学，这里再分享给大家，希望帮助更多有需求的小伙伴。一起来看看 Google 的工程师是怎么写文档的吧！
Google 的技术写作课程
Google 的技术写作课程地址：https://developers.google.cn/tech-writing
该课程侧重于技术写作，而不是普通的英语写作或商务写作。课程的学习材料都公开在了课程页面，可用于自学。
课程的目标受众：
- 专业的软件工程师
- 计算机科学专业的学生
- 工程周边角色，如产品经理
知识能力要求：
需要具备一定的英语写作能力。如果懂些编程就更好了，会更容易理解课程内容。
课程设计：
- 课程 1：初级，侧重于技术写作的基础知识，如词句、表格、列表、标点、受众、Markdown 等。链接：https://developers.google.cn/tech-writing/one
- 课程 2：中级，侧重于要求更高的一些知识点，如画图、组织大型文档、编辑优化文档、创建示例代码等。链接：https://developers.google.cn/tech-writing/two
图片源自 Google 官网
更多课程资源：
链接：https://developers.google.cn/tech-writing/resources
该资源页面提供了多个可参考的 Style Guide，均附上了在线阅读链接或 PDF 下载链接，主要有以下几个：
- The Chicago Manual of Style Online
- University of Oxford Style Guide
- Google developer documentation style guide
- Microsoft Writing Style Guide
其中，我最常使用的就是 Google developer documentation style guide 了，也强烈推荐给大家。
在日常协作中，有时需要给其他小伙伴解释某个技术写作规则，通常都能在 Google 这个 guide 里找到相关内容，直接发给对方一个具体页面的链接，清楚又高效。
例如，为什么英语技术文档中通常会限制 please 一词的使用：https://developers.google.cn/style/tone#politeness-and-use-of-please
Afterword
早前 3 月 22 日的时候，我把 Google 面向工程师的技术写作课程发到了 Hacker News 上面。注：Hacker News is a social news website focusing on computer science and entrepreneurship.
当时这个课程登上了 Hacker News 首页，引发了激烈的有意思的讨论。想了解讨论细节的小伙伴可以戳此链接：https://news.ycombinator.com/item?id=22652241
Hacker News 上的讨论，点击放大可查看大图
此外，Google 还描述了什么样的人可以成为 Google 的 Technical Writer：https://developers.google.cn/tech-writing/becoming
具体描述如下：
There is no single path to becoming a technical writer at Google. Although a few have earned degrees in technical writing, most technical writers come from other worlds. For example, you'll find plenty of software engineers, development operations engineers, journalists, physicists, lawyers, and teachers now working as technical writers at Google. Despite the wide range of educational and professional backgrounds, this diverse bunch share the following skills:
- Write clearly in English. We don't care whether English is your first language or your tenth; we only care about the quality of your writing in English.
- Learn complex technologies relatively quickly.
- Explain complex technologies in useful ways for the target audience.
- Wield strong interpersonal skills.
- Understand code.
Technical writers are rare hybrids, possessing an uncommon mixture of talents.
以上描述有助于小伙伴们了解 Technical Writer 这一岗位，还有助于参考 Google 的要求来培养自己的技能，补己之短，不断成长。
-END-
猜你想读：
征稿启事 | 技术传播圈故事征集
什么样的人适合做 Technical Writer？
英语专业的同学可以做技术文档写作吗？
技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
Write the Docs：连接技术文档人的全球社区，附海量学习资源
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
技术传播人士应该知道的色彩搭配常识
如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
行业动态 | 国内有哪些高校开设了技术传播或技术写作课程？
IEEE ProComm 2019 国际传播大会上，中国代表团有哪些精彩分享？
行业动态 | 2019 中国技术传播论坛上，大家都在谈论什么？
优质免费资源推荐 | 9 期技术写作短视频教程带你从入门到进阶
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？
Technical Writer 如何参与开源项目的文档，以不断提升专业技能?
技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”
经验分享 | 对用户文档进行伤筋动骨式的重构是怎样一种体验？
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
如何使用正则表达式批量删除多个 Markdown 文件的指定行？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
英语技术文档中如何正确使用无序列表和有序列表？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
技术文档翻译实例解析：始于翻译，经于沟通，终于易用
优质译文不应止于正确，还要 Well-Organized
Technical Writer 处理技术文档时，如何避免内容理解问题？
Technical Writer 需要 Technical 到会写代码吗？
如何利用 GitHub Pages 和 Hugo 轻松搭建个人博客？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记
网友评论