技术文档代码化开发模式

北大高志军老师首先跟大家分享了技术文档代码化开发模式，即 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 型布局

• 黄金分割

• 斐波那契弧线图

第二位分享嘉宾是来自阿里云的资深技术文档工程师彭智超。

▲ 阿里云彭智超

他主要跟大家分享了以下几点：

1. 技术文档：架起产品与用户的桥梁

2. 阿里云文档开发流程

• 新产品/功能立项

• Feature Complete

• UAT 测试

• 产品/功能发布

• 产品改进

3. 内容管理平台设计思路

1）引入 DITA 标准，基于 DITA 开发文档，制定写作规范

2）引入或者自研工具，解决版本管理和持续集成问题

4. 内容管理平台架构

5. 结构化写作之美

6. 2018 文档开源

开源项目内容运营

的实践、挑战和难点

第三位分享嘉宾是来自 PingCAP 的 I18N 部门的负责人金坤 Queeny。

哈哈，没错，就是我的 leader，也是我在北大读研的同门师姐。这个公众号的很多读者已经知道我目前就在 PingCAP 工作。

▲ PingCAP 金坤

她主要跟大家分享了开源项目内容运营的实践、挑战和难点。

其中，关于 I18N 部门所承担的工作介绍肯定让很多小伙伴感到惊讶，因为涵盖的内容实在是太广了，似乎每一项工作在很多公司里都是一个独立的团队在做。

但这就是互联网时代创业公司的需求，也是对我们的要求和期望。

我之前写过一篇文章介绍 Technical Communicator 可提供的交付物种类，绝不仅限于大家通常认为的用户文档哦。

Queeny 还跟大家分享了大概的文档流程。

在提问环节，有一个会写代码的小哥哥问到如何区分 blogger 和 Technical Writer，另有一个小姐姐问到英文技术博客那么难，是如何写出来的。

因为两个问题相关，于是 Queeny 一起回答了，给大家简单分享了一篇英文技术博客或英文案例的诞生过程。

可以说，纯翻译与一篇合格的英文技术博客或案例之间，隔了十万八千里。

感兴趣的小伙伴可以去 PingCAP 的英文官网看看 Blog 或 Success Stories 下的英文文章。

已经有参加这个沙龙的小伙伴立下了 flag，要详细研究 PingCAP 的文档，哈哈~截图为证：

▼

茶歇过后的第四位分享嘉宾是来自百度云的徐晶晶。

▲  百度云徐晶晶

她主要跟大家分享了以下几点：

1. 百度云文档的体系框架

2. 百度云文档的数据收集

3. 百度云文档的数据分析

• 主观数据+PDCA 模型保证文档稳步提升

• 客观数据验证并预测文档质量

▲  数据分析 - 主观

▲  数据分析 - 客观

4. 智能写作技术

▲  智能写作概述

▲  智能写作应用

5. 辅助写作技术

▲  辅助写作解决的问题

优劣势：

在技术文档中的应用探讨：

徐晶晶还给大家播放了个展示的小视频，看完觉得智能写作技术和辅助写作技术挺有意思。

05

用户体验设计

基本流程与方法

第五位即最后一位分享嘉宾是来自北师大用户体验研究中心的辛欣老师。

▲  北师大辛欣老师

她主要跟大家分享了下用户体验相关的知识，希望从用户体验的角度给大家写技术文档带来一些启发。

近两年，技术传播在国内的发展比较迅速。

高校纷纷开设技术写作相关的课程，技术传播行业也得到越来越多的关注，给语言专业的小伙伴提供了更多的职业选择。

沙龙活动的最后，所有参与此次技术传播沙龙的小伙伴拍了个大合影留念。

▲  合影来自高志军老师朋友圈