Foreword
2018 年 12 月 22 日，时值冬至，一场以“互联网技术写作”为主题的技术传播沙龙在北京阿里望京中心 A 座暖意浓浓地举行。来自北京大学、阿里云、PingCAP、百度云、北师大用户体验研究中心的嘉宾做了精彩的分享。
我也去参加了这个沙龙，了解了下当前技术文档在国内的发展动态和行业实践，见到了一些在北大读研时的老师和同学，以及师弟师妹们，还见到了一些我公众号的读者。
北大作为国内最早开设英语技术文档写作课程的高校，确实为该行业输出了不少人才。正如此次沙龙的发起人高志军老师所说，当前国内技术传播行业中，很多都是北大出去的同学。比如，我就是其中一个。
接下来，我将从沙龙参加者的角度来跟大家分享一下我在此次沙龙上的所见所闻，笔记不会涵盖所有内容，但可以让无法来现场的小伙伴也了解一下现在的技术传播沙龙上大家都在聊些什么。
此次分享的主要话题如下（按嘉宾分享顺序）：
- 北大高志军：Docs like code 技术文档代码化开发模式
- 阿里云彭智超：阿里云的内容开发和管理之路
- PingCAP 金坤：开源项目内容运营的实践、挑战和难点
- 百度云徐晶晶：文档的数据收集与分析+自动化写作探讨
- 北师大辛欣：用户体验设计基本流程与方法
一、北大高志军：技术文档代码化开发模式
北大高志军老师首先跟大家分享了技术文档代码化开发模式，即 Docs like code 或 Docs as code。
常见的方式是将文档源文件托管在 GitHub 上。关注行业动态的小伙伴应该已经听说过，我之前也写过两篇相关文章：
- 技术写作工具 | GitHub + Markdown 的新轻型技术写作模式速览
- 技术文档方案 | GitHub + Markdown 的深度实践解析
这种文档方案敏捷快速、成本低，便于团队协作。文档页面的布局通常会分为三大部分：
- 左侧：文档导航栏
- 中间：文档正文
- 右侧：当前文档的页面导航
此外，通常还会在文档页面给用户提供直接编辑文档的入口，即跳转至 GitHub 提 Pull Request。
业界已有很多成功案例，例如 Microsoft、Amazon、阿里云、PingCAP 等的文档。
下面以 The Microsoft Cognitive Toolkit 的文档为例，具体介绍一下。其文档页面提供了如下功能：
- 文档编辑入口：点击右上角的 Edit，即跳转至对应的 GitHub 页面。
- 白天与夜晚模式：点击右上角的 Dark 可切换至夜晚模式，点击 Light 切换至白天模式。
- 阅读时间：当前文档页面的预计阅读时间。
官网链接：https://docs.microsoft.com/en-us/cognitive-toolkit/
高老师还跟大家分享了 Sphinx 快速入门，但因为时间有限，只是匆匆带过了。另外，还快速分享了下信息设计相关的内容，提到了以下几点：
- 扁平 vs 深度
- 正文长度
- 配色
- F 型布局
- 黄金分割
- 斐波那契弧线图
二、阿里云彭智超：阿里云的内容开发和管理之路
第二位分享嘉宾是来自阿里云的资深技术文档工程师彭智超。
他跟大家主要分享了以下几点：
- 技术文档：架起产品与用户的桥梁
- 阿里云文档开发流程
- 新产品/功能立项
- Feature Complete
- UAT 测试
- 产品/功能发布
- 产品改进
- 内容管理平台设计思路
1）引入 DITA 标准，基于 DITA 开发文档，制定写作规范
2）引入或者自研工具，解决版本管理和持续集成问题
- 内容管理平台架构
- 结构化写作之美
- 2018 文档开源
三、PingCAP 金坤：开源项目内容运营的实践、挑战和难点
第三位分享嘉宾是来自 PingCAP 的 I18N 部门的负责人金坤 Queeny。
哈哈，没错，就是我的 leader，也是我在北大读研的同门师姐。这个公众号的很多读者已经知道我目前就在 PingCAP 工作。
她主要跟大家分享了开源项目内容运营的实践、挑战和难点。
其中，关于 I18N 部门所承担的工作介绍肯定让很多小伙伴感到惊讶，因为涵盖的内容实在是太广了，似乎每一项工作在很多公司里都是一个独立的团队在做。但这就是互联网时代创业公司的需求，也是对我们的要求和期望。
我之前写过一篇文章介绍 Technical Communicator 可提供的交付物种类，绝不仅限于大家通常认为的用户文档哦。
Queeny 还跟大家分享了大概的文档流程。
在提问环节，有一个会写代码的小哥哥问到如何区分 blogger 和 Technical Writer，另有一个小姐姐问到英文技术博客那么难，是如何写出来的。
因为两个问题相关，于是 Queeny 一起回答了，给大家简单分享了一篇英文技术博客或英文案例的诞生过程。可以说，纯翻译与一篇合格的英文技术博客或案例之间，隔了十万八千里。
感兴趣的小伙伴可以去 PingCAP 的英文官网看看 Blog 或 Success Stories 下的英文文章。
已经有参加这个沙龙的小伙伴立下了 flag，要详细研究 PingCAP 的文档，哈哈~
四、百度云徐晶晶：文档的数据收集与分析+自动化写作探讨
茶歇过后的第四位分享嘉宾是来自百度云的徐晶晶。
她主要跟大家分享了以下几点：
- 百度云文档的体系框架
- 百度云文档的数据收集
- 百度云文档的数据分析
- 主观数据+PDCA 模型保证文档稳步提升
- 客观数据验证并预测文档质量
- 智能写作技术
- 辅助写作技术
优劣势：
在技术文档中的应用探讨：
徐晶晶还给大家播放了个展示的小视频，看完觉得智能写作技术和辅助写作技术挺有意思。
五、北师大辛欣：用户体验设计基本流程与方法
第五位即最后一位分享嘉宾是来自北师大用户体验研究中心的辛欣老师。
她主要跟大家分享了下用户体验相关的知识，希望从用户体验的角度给大家写技术文档带来一些启发。
Afterword
近两年，技术传播在国内的发展比较迅速。
高校纷纷开设技术写作相关的课程，技术传播行业也得到越来越多的关注，给语言专业的小伙伴提供了更多的职业选择。
沙龙活动的最后，所有参与此次技术传播沙龙的小伙伴拍了个大合影留念。
你可能想读：
技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
技术传播人士应该知道的色彩搭配常识
如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记
-END-