如何寫好開源文檔~看完助你輕松上手！

時間：2023-05-25 00:51:01 | 來源：網(wǎng)站運營

時間：2023-05-25 00:51:01 來源：網(wǎng)站運營

如何寫好開源文檔~看完助你輕松上手！：開源項目下，代碼解決技術(shù)問題，而文檔則幫助你使用這些代碼。
對于很多人來說，開源項目中的文檔對于使用開源代碼起到了關(guān)鍵的作用，也是許多技術(shù)愛好者較為關(guān)注的內(nèi)容，技術(shù)愛好者通過文檔學(xué)習(xí)使用開源代碼，也可以通過文檔指導(dǎo)去貢獻(xiàn)代碼。
那么對于專門服務(wù)開源產(chǎn)品下的技術(shù)文檔工程師，與其他行業(yè)的技術(shù)文檔工程師，工作中，有哪些不同點和相同點呢？
首先我們先了解一下開源行業(yè)有哪些特點。
開源行業(yè)特點是什么？
軟件的“源”即其源代碼，“開源”的核心概念是軟件的編寫者將源代碼免費提供給使用者，同時要求使用者遵循一定的開源規(guī)范。開放源代碼促進(jìn)會（Open Source Initiative，縮寫：OSI）是一個旨在推動開源軟件發(fā)展的非盈利組織。OSI 組織在規(guī)范了開源項目和軟件的開源要求以外，也在開源許可（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è)。
其實開源行業(yè)還是有很顯著的特點的，從而讓很多技術(shù)行業(yè)趨之若鶩：

• 自由性：開源的發(fā)起者可以是個人、企業(yè)等各種主體；開源與商業(yè)化并不矛盾，開源軟件的“引流”作用能夠幫助企業(yè)或個體實現(xiàn)周邊產(chǎn)品的增收、市場影響力的提升以及產(chǎn)業(yè)生態(tài)的協(xié)同構(gòu)建。
• 開放式協(xié)作：源代碼自由的被訪問，技術(shù)愛好者共同改進(jìn)代碼，協(xié)同合作，資源透明，可以自行追蹤代碼更新，無需跟進(jìn)或被綁定到某個產(chǎn)品的服務(wù)中。
• 專業(yè)可靠：開源代碼的存在時間可以超越其原作者對它更新的時間，活躍的開源社區(qū)幫助代碼進(jìn)行不斷地更新。開放標(biāo)準(zhǔn)和同行評審可以確保開源代碼可以經(jīng)常得到適當(dāng)?shù)臏y試。
• 靈活性：由于開源代碼可靈活修改，因此您可以使用它來解決您的業(yè)務(wù)或社區(qū)面臨的獨特問題。您無需只使用一種特定方式使用代碼，您可以依托社區(qū)幫助和同行評審幫助您實施新解決方案。
• 成本更低：源代碼公開免費，可以跟進(jìn)代碼更新，也可以進(jìn)行二次開發(fā)。

開源行業(yè)文檔的特點是什么？


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

• 文檔受眾：開源行業(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è)有一些時間卡點，以保證最新代碼與最新文檔能保持同期更新。
• 更低成本：文檔可以通過文檔構(gòu)建平臺直接承載，并發(fā)布為網(wǎng)頁。

開源行業(yè)技術(shù)文檔工程師的價值是什么？


作為一個技術(shù)文檔工程師，無論服務(wù)于什么行業(yè)，無論寫什么產(chǎn)品的文檔，基本的核心都是不變的。例如你必須有用戶分析的能力、任務(wù)分析的能力、溝通能力、文檔工具鏈的使用能力、流程管理能力以及質(zhì)量管控的能力。即便是沒有開源文檔經(jīng)驗的各位技術(shù)文檔寫作者，也可以借鑒很多閉源產(chǎn)品的寫作經(jīng)驗。
開源行業(yè)文檔工作評價體系與閉源行業(yè)文檔稍有不同，最大的區(qū)別是對于用戶問題的響應(yīng)速度非?？?。我們在考察開源文檔工程師 KPI 時或者獲取最直接用戶體驗的時候，相應(yīng)的數(shù)據(jù)也更加直觀。

• KPI考核：那么如何去考核一個開源文檔工程師的KPI呢，一般情況下，可以最直接的在 Git 上檢查提交的 PR 的數(shù)量和質(zhì)量，以及解決 Issue 的數(shù)量，在社區(qū)的活躍度也可以充分體現(xiàn)日常文檔工作。 Issue 的解決方案也可以看得出來是解決了文檔的 bug 還是助推了產(chǎn)品的優(yōu)化，多維度評價一個文檔工程師的工作價值。
• 降本增效：開源文檔同代碼一樣，直接面向大眾，技術(shù)愛好者會直接貢獻(xiàn)代碼和文檔到 Git，他們遇到的問題也會直接反應(yīng)到 Git 的 Issue 里，你直接面對這些問題，而文檔就是去幫助他們?nèi)ソ鉀Q問題的，節(jié)省了很多需要特意去做調(diào)查問卷或者去做用戶訪談去挖掘問題的時間，也能迅速響應(yīng)這些問題，無論是你的文檔本身去響應(yīng)這些問題，還是技術(shù)工程師去響應(yīng)問題，問題的產(chǎn)生，問題的記錄，以及問題的解決，答案的記錄，都可以形成文檔，幫助開源企業(yè)降本增效。
• 用戶行為采集與分析：對文檔網(wǎng)站做埋點，可以采集到開源文檔社區(qū)用戶行為，并產(chǎn)生分析報告。你可以讓前端工程師幫忙在文檔社區(qū)或者文檔網(wǎng)站上做埋點，引入 Google Analytics 或者其他用戶分析模式，通過對網(wǎng)站流量（主要是從：獨立訪問者數(shù)量（unique visitors，UV）、重復(fù)訪問者數(shù)量（repeat visitors）、頁面瀏覽數(shù)（page views，PV）、每個訪問者的頁面瀏覽數(shù)（page views per user）這幾個維度）數(shù)據(jù)的分析，以及對用戶行為（用戶的來源網(wǎng)站、用戶的搜索引擎和關(guān)鍵字、用戶在該網(wǎng)站上的停留時間、不同時間段的用戶訪問量、用戶的瀏覽的設(shè)備類型、用戶的瀏覽器的名稱和版本、用戶的屏幕分辨率、用戶的操作系統(tǒng)名稱和版本、用戶所在地理區(qū)域分布）進(jìn)行分析，提取關(guān)鍵信息，優(yōu)化文檔質(zhì)量。這些數(shù)據(jù)非常真實，你可以通過這些數(shù)據(jù)，去思考如何去調(diào)整文檔結(jié)構(gòu)，定位文檔屬性，為你的用戶提供什么幫助，解決什么問題，更好的去運營你的文檔社區(qū)。
• 用戶轉(zhuǎn)化率：一部分技術(shù)愛好者都是通過產(chǎn)品的介紹，軟件使用的介紹選擇去試用開源產(chǎn)品，如果文檔幫助他們解決了技術(shù)上的難題，那么迅速將轉(zhuǎn)化為深度用戶，反之，會失去一部分技術(shù)愛好者的貢獻(xiàn)度。另外一部分技術(shù)愛好者，是產(chǎn)品運營吸引過來，試用開源產(chǎn)品，閱讀文檔尋找解決方案進(jìn)而轉(zhuǎn)化為深度用戶的。開源文檔它對技術(shù)的描述和指導(dǎo)更加詳盡，它的閱讀量和起到的作用是非常大的。你可能在使用某些指令進(jìn)行操作的時候，遇到了困難，不用在網(wǎng)絡(luò)上搜索海量的答案，并反復(fù)驗證測試，你可以參考直接文檔，也可以直接提交問題給開源產(chǎn)品，你得到答案也很快。它區(qū)別于閉源產(chǎn)品，閉源產(chǎn)品面對技術(shù)問題或業(yè)務(wù)問題時，可能反饋給你的答案是郵件或者其他工單報告，體現(xiàn)在文檔中可能需要等到產(chǎn)品GA，而開源社區(qū)隨時都可以回答你的問題。開源產(chǎn)品本身也可以為其開源文檔引流，吸引大批技術(shù)愛好者參與代碼或文檔貢獻(xiàn)。

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


開源行業(yè)技術(shù)文檔工程師的技能樹


我們從 tcworld 2022 年技術(shù)傳播大會上曾奕霖的分享上截取了部分內(nèi)容，非常有價值，為我們開源行業(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ù)難點時，能自己通過操作代碼去執(zhí)行一些測試，發(fā)現(xiàn)問題，并解決問題，或者助推代碼進(jìn)行優(yōu)化更新。
另外就是對于一些常用的命令行，無論是 Git 指令還是本地測試指令，需要給自己的簡單的代碼能力做一個提升。



高級版


現(xiàn)在我們技術(shù)文檔工程師的技能樹需要提升到高級版，那么會面臨什么樣的挑戰(zhàn)呢？
其實也是我們對技術(shù)能夠繼續(xù)保持熱愛并且能真的愿意深入了解技術(shù)，自我驅(qū)動去研究技術(shù)，雖然對技術(shù)文檔工程師的代碼能力沒有硬性的要求，但是我們?nèi)绻莆樟艘欢ǖ臏y試技巧，數(shù)據(jù)分析或者文檔模板管理，自動化文檔測試或發(fā)布流程的話，對我們來說，不僅僅是能力提升，還讓我們對我們整個產(chǎn)品的技術(shù)框架、對我們文檔所依托的的整個技術(shù)框架，有了更清晰的理解和認(rèn)識，我們不會再僅僅沉浸于寫作本身，而是對整個產(chǎn)品或者整個產(chǎn)品文檔也會有更全局觀的認(rèn)識，才能不斷地驅(qū)動文檔質(zhì)量做出提升。
另外通過全局觀，你也可以對產(chǎn)品提出優(yōu)化建議，你是直觀感受用戶體驗好與差的人，文檔可以讓你在閱讀或者寫作時，真正站在用戶角度思考產(chǎn)品。


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



推薦的一些工具和軟件




一般寫開源文檔的工作流



寫作工具推薦：

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

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

Markdown preview Github Styling
Markdown All in One
Chinese 中文包

• Typora
• Atom（軟件已停止升級，但是可以下載使用）
• Mark Text/Notable/Sublime Text /Trilium

文檔源碼托管平臺推薦：
一般開源公司是代碼托管在哪里，文檔也托管在哪里，類似于CMS。有一些開源公司文檔中心還沒有成型，一直放在公司內(nèi)部的 wiki 站點，需要把文檔整合到托管平臺，那么我們優(yōu)先考慮跟代碼托管的平臺放在同一個地方，從代碼引流，讓更多的技術(shù)愛好者關(guān)注我們的文檔。一般情況下，代碼托管的平臺主要是：gitee/gitlab/github/gitshell。
有個穩(wěn)定源碼的托管平臺，那么我們還可以引入一個文檔網(wǎng)站生成的框架，讓技術(shù)同學(xué)做技術(shù)支持，把結(jié)構(gòu)化的文檔源碼搭建成為文檔網(wǎng)站，我們推薦一些典型的開源文檔框架：readthedocs/mkdocs/docusaurus。
我們也可以在寫作文檔的過程中，使用一些腳本工具檢查文檔內(nèi)容是否正確，可以結(jié)合公司的文檔框架，讓開發(fā)同學(xué)幫忙寫一些腳本工具，嵌入到托管平臺中，自動校驗文檔的正確性。例如可以開發(fā)一些檢查壞鏈的腳本工具 Broken link checker，或者檢查是否有冗余空行的腳本工具Blank checker。







參考文獻(xiàn)和作者

參考來源	參考內(nèi)容	原作者
tcworld 2022 年技術(shù)傳播大會	《文檔工程師的開源體驗、技能樹和工具分享》	曾奕霖
維基百科	開源軟件介紹