Foreword
2018 年 12 月 22 日，時值冬至，一場以“互聯網技術寫作”為主題的技術傳播沙龍在北京阿里望京中心 A 座暖意濃濃地舉行。來自北京大學、阿里云、PingCAP、百度云、北師大用戶體驗研究中心的嘉賓做了精彩的分享。
我也去參加了這個沙龍，了解了下當前技術文檔在國內的發展動態和行業實踐，見到了一些在北大讀研時的老師和同學，以及師弟師妹們，還見到了一些我公眾號的讀者。
北大作為國內最早開設英語技術文檔寫作課程的高校，確實為該行業輸出了不少人才。正如此次沙龍的發起人高志軍老師所說，當前國內技術傳播行業中，很多都是北大出去的同學。比如，我就是其中一個。
接下來，我將從沙龍參加者的角度來跟大家分享一下我在此次沙龍上的所見所聞，筆記不會涵蓋所有內容，但可以讓無法來現場的小伙伴也了解一下現在的技術傳播沙龍上大家都在聊些什么。
此次分享的主要話題如下（按嘉賓分享順序）：
- 北大高志軍：Docs like code 技術文檔代碼化開發模式
- 阿里云彭智超：阿里云的內容開發和管理之路
- PingCAP 金坤：開源項目內容運營的實踐、挑戰和難點
- 百度云徐晶晶：文檔的數據收集與分析+自動化寫作探討
- 北師大辛欣：用戶體驗設計基本流程與方法
一、北大高志軍：技術文檔代碼化開發模式
北大高志軍老師首先跟大家分享了技術文檔代碼化開發模式，即 Docs like code 或 Docs as code。
常見的方式是將文檔源文件托管在 GitHub 上。關注行業動態的小伙伴應該已經聽說過，我之前也寫過兩篇相關文章：
這種文檔方案敏捷快速、成本低，便于團隊協作。文檔頁面的布局通常會分為三大部分：
- 左側：文檔導航欄
- 中間：文檔正文
- 右側：當前文檔的頁面導航
此外，通常還會在文檔頁面給用戶提供直接編輯文檔的入口，即跳轉至 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-
