開源項(xiàng)目下，代碼解決技術(shù)問題，而文檔則幫助你使用這些代碼。

對于很多人來說，開源項(xiàng)目中的文檔對于使用開源代碼起到了關(guān)鍵的作用，也是許多技術(shù)愛好者較為關(guān)注的內(nèi)容，技術(shù)愛好者通過文檔學(xué)習(xí)使用開源代碼，也可以通過文檔指導(dǎo)去貢獻(xiàn)代碼。

那么，專門服務(wù)開源產(chǎn)品下的技術(shù)文檔工程師與其他行業(yè)的技術(shù)文檔工程師相比，工作中有哪些不同點(diǎn)和相同點(diǎn)呢？

1. 開源行業(yè)的特點(diǎn)是什么？

軟件的“源”即其源代碼，“開源”的核心概念是軟件的編寫者將源代碼免費(fèi)提供給使用者，同時(shí)要求使用者遵循一定的開源規(guī)范。開放源代碼促進(jìn)會（Open Source Initiative，縮寫：OSI）是一個(gè)旨在推動(dòng)開源軟件發(fā)展的非盈利組織。OSI 組織在規(guī)范了開源項(xiàng)目和軟件的開源要求以外，也在開源許可（open source license）上滿足關(guān)于源代碼的使用和修改、關(guān)于軟件傳播以及公平性、中立性等方面的諸多要求，這些要求加強(qiáng)了開源產(chǎn)業(yè)的規(guī)范性，構(gòu)建了諸多開源商業(yè)模式的基礎(chǔ)。

我們所熟悉的一些開源行業(yè)類似于Linux Kernel, Git, MySQL等，他們代碼開源，技術(shù)工程師齊力貢獻(xiàn)代碼，現(xiàn)在成為了開源界的Top行業(yè)。

其實(shí)開源行業(yè)還是有很顯著的特點(diǎn)的，從而讓很多技術(shù)行業(yè)趨之若鶩：

• 自由性：開源的發(fā)起者可以是個(gè)人、企業(yè)等各種主體；開源與商業(yè)化并不矛盾，開源軟件的“引流”作用能夠幫助企業(yè)或個(gè)體實(shí)現(xiàn)周邊產(chǎn)品的增收、市場影響力的提升以及產(chǎn)業(yè)生態(tài)的協(xié)同構(gòu)建。

• 開放式協(xié)作：源代碼可被自由地訪問，技術(shù)愛好者共同改進(jìn)代碼，協(xié)同合作，資源透明，可以自行追蹤代碼更新，無需跟進(jìn)或被綁定到某個(gè)產(chǎn)品的服務(wù)中。

• 專業(yè)可靠：開源代碼的存在時(shí)間可以超越其原作者對它更新的時(shí)間，活躍的開源社區(qū)幫助代碼進(jìn)行不斷地更新。開放標(biāo)準(zhǔn)和同行評審可以確保開源代碼可以經(jīng)常得到適當(dāng)?shù)臏y試。

• 靈活性：由于開源代碼可靈活修改，因此可以使用它來解決您的業(yè)務(wù)或社區(qū)面臨的獨(dú)特問題。無需只使用一種特定方式使用代碼，可以依托社區(qū)幫助和同行評審幫助您實(shí)施新解決方案。

• 成本更低：源代碼公開免費(fèi)，可以跟進(jìn)代碼更新，也可以進(jìn)行二次開發(fā)。

2.開源行業(yè)文檔的特點(diǎn)是什么？

在開源軟件代碼飛速發(fā)展的情況下，隨之對開源代碼使用和技術(shù)解釋的開源文檔也面臨一些挑戰(zhàn)。其實(shí)開源行業(yè)文檔和閉源行業(yè)的文檔有一些共通性，但是也有一些差異點(diǎn)，開源行業(yè)的文檔特點(diǎn)比較鮮明：

• 文檔受眾：開源行業(yè)文檔它的主要面向受眾就是首先是開發(fā)者，他們關(guān)注軟件如何安裝部署調(diào)試以及對其進(jìn)行二次開發(fā)；其次是友商或者競商，他們關(guān)注軟件使用難易度，定制化服務(wù)成本，優(yōu)化空間，是否可以直接選用，對其他工具依賴度高不高等等。

• 協(xié)作方式：開源文檔寫作的協(xié)作方式更為開放，開源公司的技術(shù)文檔工程師是主要寫作者，但是他的協(xié)作者可以是公司內(nèi)部同事，也可以是貢獻(xiàn)代碼的技術(shù)愛好者，也可以是其他公司的技術(shù)寫作同行，協(xié)作對象面向大眾。

• 文檔載體：以網(wǎng)頁的形式展示文檔內(nèi)容。區(qū)別于傳統(tǒng)文檔，承載傳統(tǒng)文檔的媒介主要是PDF/紙質(zhì)文檔及.chm 格式的幫助文檔。開源行業(yè)的文檔形式更為豐富，但是它主要是以響應(yīng)式網(wǎng)頁的形式承載文檔。

• 發(fā)布周期：開源文檔發(fā)布周期非常靈活，即更新即發(fā)布，當(dāng)然不同的開源公司的文檔在發(fā)布的流程中設(shè)有一些時(shí)間卡點(diǎn)，以保證最新代碼與最新文檔能保持同期更新。

• 更低成本：文檔可以通過文檔構(gòu)建平臺直接承載，并發(fā)布為網(wǎng)頁。

3.開源行業(yè)技術(shù)文檔

工程師的價(jià)值是什么？

作為一個(gè)技術(shù)文檔工程師，無論服務(wù)于什么行業(yè)，無論寫什么產(chǎn)品的文檔，基本的核心都是不變的。例如你必須有用戶分析能力、任務(wù)分析能力、溝通能力、文檔工具鏈?zhǔn)褂媚芰?、流程管理能力以及質(zhì)量管控能力。即便是沒有開源文檔經(jīng)驗(yàn)的各位技術(shù)文檔寫作者，也可以借鑒很多閉源產(chǎn)品的寫作經(jīng)驗(yàn)。

開源行業(yè)文檔工作評價(jià)體系與閉源行業(yè)文檔稍有不同，最大的區(qū)別是對于用戶問題的響應(yīng)速度非?？?/strong>。我們在考察開源文檔工程師 KPI 時(shí)或者獲取最直接用戶體驗(yàn)的時(shí)候，相應(yīng)的數(shù)據(jù)也更加直觀。

• KPI考核：那么如何去考核一個(gè)開源文檔工程師的KPI呢？一般情況下，可以最直接的在 Git 上檢查提交的 PR 的數(shù)量和質(zhì)量，以及解決 Issue 的數(shù)量，在社區(qū)的活躍度也可以充分體現(xiàn)日常文檔工作。Issue 的解決方案也可以看得出來是解決了文檔的 bug 還是助推了產(chǎn)品的優(yōu)化，多維度評價(jià)一個(gè)文檔工程師的工作價(jià)值。

  
  

• 降本增效：開源文檔同代碼一樣，直接面向大眾，技術(shù)愛好者會直接貢獻(xiàn)代碼和文檔到 Git，他們遇到的問題也會直接反應(yīng)到 Git 的 Issue 里，你直接面對這些問題，而文檔就是去幫助他們?nèi)ソ鉀Q問題的，節(jié)省了很多需要特意去做調(diào)查問卷或者去做用戶訪談去挖掘問題的時(shí)間，也能迅速響應(yīng)這些問題，無論是你的文檔本身去響應(yīng)這些問題，還是技術(shù)工程師去響應(yīng)問題，問題的產(chǎn)生，問題的記錄，以及問題的解決，答案的記錄，都可以形成文檔，幫助開源企業(yè)降本增效。

  
  

• 用戶行為采集與分析：對文檔網(wǎng)站做埋點(diǎn)，可以采集到開源文檔社區(qū)用戶行為，并產(chǎn)生分析報(bào)告。你可以讓前端工程師幫忙在文檔社區(qū)或者文檔網(wǎng)站上做埋點(diǎn)，引入 Google Analytics 或者其他用戶分析模式，通過對網(wǎng)站流量（主要是從：獨(dú)立訪問者數(shù)量（unique visitors，UV）、重復(fù)訪問者數(shù)量（repeat visitors）、頁面瀏覽數(shù)（page views，PV）、每個(gè)訪問者的頁面瀏覽數(shù)（page views per user）這幾個(gè)維度）數(shù)據(jù)的分析，以及對用戶行為（用戶的來源網(wǎng)站、用戶的搜索引擎和關(guān)鍵字、用戶在該網(wǎng)站上的停留時(shí)間、不同時(shí)間段的用戶訪問量、用戶的瀏覽的設(shè)備類型、用戶的瀏覽器的名稱和版本、用戶的屏幕分辨率、用戶的操作系統(tǒng)名稱和版本、用戶所在地理區(qū)域分布）進(jìn)行分析，提取關(guān)鍵信息，優(yōu)化文檔質(zhì)量。這些數(shù)據(jù)非常真實(shí)，你可以通過這些數(shù)據(jù)，去思考如何去調(diào)整文檔結(jié)構(gòu)，定位文檔屬性，為你的用戶提供什么幫助，解決什么問題，更好的去運(yùn)營你的文檔社區(qū)。

  
  

• 用戶轉(zhuǎn)化率：一部分技術(shù)愛好者都是通過產(chǎn)品的介紹，軟件使用的介紹選擇去試用開源產(chǎn)品，如果文檔幫助他們解決了技術(shù)上的難題，那么迅速將轉(zhuǎn)化為深度用戶，反之，會失去一部分技術(shù)愛好者的貢獻(xiàn)度。另外一部分技術(shù)愛好者，是產(chǎn)品運(yùn)營吸引過來，試用開源產(chǎn)品，閱讀文檔尋找解決方案進(jìn)而轉(zhuǎn)化為深度用戶的。開源文檔它對技術(shù)的描述和指導(dǎo)更加詳盡，它的閱讀量和起到的作用是非常大的。你可能在使用某些指令進(jìn)行操作的時(shí)候，遇到了困難，不用在網(wǎng)絡(luò)上搜索海量的答案，并反復(fù)驗(yàn)證測試，你可以參考直接文檔，也可以直接提交問題給開源產(chǎn)品，你得到答案也很快。它區(qū)別于閉源產(chǎn)品，閉源產(chǎn)品面對技術(shù)問題或業(yè)務(wù)問題時(shí)，可能反饋給你的答案是郵件或者其他工單報(bào)告，體現(xiàn)在文檔中可能需要等到產(chǎn)品GA，而開源社區(qū)隨時(shí)都可以回答你的問題。開源產(chǎn)品本身也可以為其開源文檔引流，吸引大批技術(shù)愛好者參與代碼或文檔貢獻(xiàn)。

總之，對于用戶的反饋，開源文檔社區(qū)的速度都是很快的，我們可以跟用戶直接面對面。

4.開源行業(yè)技術(shù)文檔

工程師的技能樹

我們從 tcworld 2022 年技術(shù)傳播大會上曾奕霖的分享中截取了部分內(nèi)容，非常有價(jià)值，為我們開源行業(yè)的文檔工程師的技能培養(yǎng)提供了方向。

他在大會中將技能樹分為基礎(chǔ)版，進(jìn)階版和高級版，在文檔工程師本職技術(shù)寫作的基礎(chǔ)上，提出了其他的需要具備的能力。

基礎(chǔ)版

既然是給開源產(chǎn)品寫文檔，那么對于文檔工程師基礎(chǔ)能力除了最基礎(chǔ)的制圖能力（即畫圖、制表以及處理圖片），還需要有 Doc as code 的寫作能力。

如何理解 Doc as code 的寫作能力，結(jié)合下圖，從 Git basics 和 CLI basics 開始看，你需要掌握 Git 指令，會執(zhí)行一些本地命令，并且你可以熟練使用 Markdown 或 XML 進(jìn)行文檔寫作。

進(jìn)階版

那么在基礎(chǔ)版的基礎(chǔ)上，文檔工程師有需要增加更多的技能。

你必須學(xué)會在寫作過程中發(fā)現(xiàn)問題并解決問題，這不僅包括對文檔的測試，也包括在編寫技術(shù)難點(diǎn)時(shí)，能自己通過操作代碼去執(zhí)行一些測試，發(fā)現(xiàn)問題，并解決問題，或者助推代碼進(jìn)行優(yōu)化更新。

另外就是對于一些常用的命令行，無論是 Git 指令還是本地測試指令，需要給自己的簡單的代碼能力做一個(gè)提升。

高級版

現(xiàn)在我們技術(shù)文檔工程師的技能樹需要提升到高級版，那么會面臨什么樣的挑戰(zhàn)呢？

其實(shí)也是我們對技術(shù)能夠繼續(xù)保持熱愛并且能真的愿意深入了解技術(shù)，自我驅(qū)動(dòng)去研究技術(shù)，雖然對技術(shù)文檔工程師的代碼能力沒有硬性的要求，但是我們?nèi)绻莆樟艘欢ǖ?strong>測試技巧，數(shù)據(jù)分析或者文檔模板管理，自動(dòng)化文檔測試或發(fā)布流程的話，對我們來說，不僅僅是能力提升，還讓我們對我們整個(gè)產(chǎn)品的技術(shù)框架、對我們文檔所依托的的整個(gè)技術(shù)框架，有了更清晰的理解和認(rèn)識，我們不會再僅僅沉浸于寫作本身，而是對整個(gè)產(chǎn)品或者整個(gè)產(chǎn)品文檔也會有更全局觀的認(rèn)識，才能不斷地驅(qū)動(dòng)文檔質(zhì)量做出提升。

另外通過全局觀，你也可以對產(chǎn)品提出優(yōu)化建議，你是直觀感受用戶體驗(yàn)好與差的人，文檔可以讓你在閱讀或者寫作時(shí)，真正站在用戶角度思考產(chǎn)品。

你可以試著驅(qū)動(dòng)自己對技術(shù)點(diǎn)的測試能力，對文檔閱讀量做數(shù)據(jù)分析，對文檔架構(gòu)或者未來規(guī)劃有全局觀的認(rèn)識，對改造文檔網(wǎng)站樣式、布局做出新的規(guī)劃，對于文檔整個(gè)開發(fā)流程中提出自動(dòng)化建議。

5.推薦的一些工具和軟件

工欲善其事，必先利其器。

寫作工具推薦

一般情況來說，開源行業(yè)技術(shù)文檔工程師平時(shí)寫作的文檔類型和寫作的語法一般是markdown，主要是為了快速寫作，不再關(guān)注文檔的格式，“把文檔渲染得漂亮”這部分工作交給設(shè)計(jì)師，交給前端工程師，而我們把我們的主要精力放在我們輸出內(nèi)容是否準(zhǔn)確，用戶體驗(yàn)是否友好上面。

我們推薦一些適合平時(shí)文檔寫作一些比較典型的 Markdown 編輯器。

• Visual Studio Code：對于使用 Visual Studio Code 的同學(xué)，也可以使用一些輔助的插件，比如實(shí)時(shí)預(yù)覽或者安裝漢化包：

- Markdown preview Github Styling

- Markdown All in One

- Chinese 中文包

• Typora

• Atom（軟件已停止升級，但是可以下載使用）

• Mark Text/Notable/Sublime Text /Trilium

文檔源碼托管平臺推薦

一般開源公司是代碼托管在哪里，文檔也托管在哪里，類似于CMS。有一些開源公司文檔中心還沒有成型，一直放在公司內(nèi)部的 wiki 站點(diǎn)，需要把文檔整合到托管平臺，那么我們優(yōu)先考慮跟代碼托管的平臺放在同一個(gè)地方，從代碼引流，讓更多的技術(shù)愛好者關(guān)注我們的文檔。一般情況下，代碼托管的平臺主要是：gitee/gitlab/github/gitshell。

有個(gè)穩(wěn)定源碼的托管平臺，那么我們還可以引入一個(gè)文檔網(wǎng)站生成的框架，讓技術(shù)同學(xué)做技術(shù)支持，把結(jié)構(gòu)化的文檔源碼搭建成為文檔網(wǎng)站，我們推薦一些典型的開源文檔框架：readthedocs/mkdocs/docusaurus。

我們也可以在寫作文檔的過程中，使用一些腳本工具檢查文檔內(nèi)容是否正確，可以結(jié)合公司的文檔框架，讓開發(fā)同學(xué)幫忙寫一些腳本工具，嵌入到托管平臺中，自動(dòng)校驗(yàn)文檔的正確性。例如可以開發(fā)一些檢查壞鏈的腳本工具 Broken link checker，或者檢查是否有冗余空行的腳本工具Blank checker。

6.我的一些感悟

我是來自開源軟件的一名技術(shù)寫作者，在這個(gè)行業(yè)里從業(yè)時(shí)間不久，但是感觸頗深。

首先是和其他工程師協(xié)作與沉浸寫作的旅程變得短而緊湊，面對大量涌入的 Issue 和 Project request comments，需要第一時(shí)間進(jìn)行響應(yīng)，并且需要及時(shí)反饋給用戶，或者給出解決方案，或者給出答復(fù)時(shí)間。

另外就是自我驅(qū)動(dòng)，一方面是驅(qū)動(dòng)自己技能樹的進(jìn)階，另一方面是驅(qū)動(dòng)自己主動(dòng)推動(dòng)文檔驗(yàn)證的流程，開源軟件下的每一個(gè)崗位的工程師的檔期都需要自己去主動(dòng)搶占，讓他們積極參與到文檔質(zhì)量管控流程中來。

還有最重要的仍然是寫作能力，這個(gè)是我們最基礎(chǔ)的能力，也仍然是需要日益打磨精進(jìn)的能力，永遠(yuǎn)不能說自己的文檔是最完美的，文檔它永遠(yuǎn)是有改進(jìn)和優(yōu)化的空間，面對變化的閱讀行為、科技平臺的創(chuàng)新、或者最新的用戶體驗(yàn)潮流（例如 AI)，我們文檔人不但需要有想象力、更需要有最佳實(shí)踐的能力，去拓寬我們的文檔道路，經(jīng)營好我們文檔業(yè)務(wù)。

7.參考文獻(xiàn)

• 曾奕霖，tcworld 2022 年技術(shù)傳播大會：文檔工程師的開源體驗(yàn)、技能樹和工具分享

• 維基百科：

  https://zh.m.wikipedia.org/zh-sg/%E5%BC%80%E6%BA%90%E8%BD%AF%E4%BB%B6