像書寫代碼一樣撰寫文檔

不想讓文檔成為事後的想法？或許你該嘗試一下全新的寫作方式。

很多工程師與手工藝者都對他們使用的工具有特別的要求。為了順利的完成工作，你需要最好的工具和使用它們的技巧。軟體開發中最好的工具在應用到其他的數字創作領域中也可以是很強大的。 文檔即代碼 Docs as Code 的方式就是很好的例子。「文檔即代碼」意味著使用與代碼開發相同的工具和工作流來撰寫文檔。文檔即代碼的支持者認為，這樣的方式可以在降低寫作者的工作量的同時，也帶來了更好的文檔。

文本格式與源文件控制

從傳統的寫作平台切換到文檔即代碼方式時，最主要的調整是將寫作內容保存在基於文本的標記格式中。這一轉變使得基於純文本的工具都適用於文檔寫作。無論你選擇 DocBook、Markdown 或者其他的標記語言，從只使用一種工具到使用一種標準格式配合多種工具是一種巨大的轉變。

找到支持你的工作流程的工具是非常重要的。很多開發者在文檔即代碼項目中使用他們的 代碼編輯器。因為他們已經是這些工具的高階用戶，一切都很順利。而找到適合團隊里其他專業人員，比如技術撰稿、編輯、信息架構師和文檔產品責任人的工具可能需要一番努力。這裡有一些選項可供參考：

• 各種 優秀的 Markdown 編輯器 之一
• 附帶良好的預覽工具的代碼編輯器可能更適合非程序員
• 流行的 Git 託管服務的網頁界面尤其適用於偶爾有需要的貢獻者

一旦內容以標記語言的格式安全地保存，就可以使用 Git 這樣的版本控制進行管理。Git 相比大多數文檔平台具有更多的功能：

• 清晰詳細的文檔版本歷史：誰在什麼時候改變了什麼。如果你有良好的提交信息慣例，你甚至可以了解到為什麼會有這樣的變更。
• 簡明的並行修改過程。在 Git 中使用分支工作意味著任何人可以做出他們想要的任何改變，並在最後合併所做的變更。
• 先進的協作與審查工具。所有的源代碼管理平台都被設計成支持詳細審查每一個變更，並根據需要進行討論，使每個人都確信這個變更可以繼續進行。
• 自動質量檢查，比如拼寫檢查和鏈接檢查。這不僅節省了時間，而且可以發現可能遺漏的錯誤。

源代碼管理有很多優點。但要記住，如果你準備入門源代碼管理，它有一定的學習曲線。這是一些有助於撰寫者入門的優秀的 學習資源 和 文章。你也可以讓具有好奇心的文檔撰寫者自行尋找對他們有用的學習材料，而不是請你的工程師來培訓他們。（問我是怎麼學會的？ —— 當然是通過艱苦的方式！）

拉取請求和評審循環

所有的源代碼管理平台都圍繞 拉取請求 Pull Request 這一概念設計的，這有時也稱為 合併請求Merge Request：有時候，某個人或某個團隊先將一系列改變整合到一起，然後請求把這些修改拉到主項目中。不過從許多方面來說，在文檔中一次處理多個變更比在代碼中更容易。改變一篇文章中的某個地方，比更改代碼並發現有其它幾個地方依賴它，副作用更小。

最強大的協作工具是 diff，它可以通過一個易於理解的方式展示舊版本與新版本之間的差異。該工具有許多不同的版本，可以使比較視圖更易於查看：雙欄模式、行內模式，甚至是渲染過的 Markdown 模式。團隊中的每一個成員都可以選擇最適合他們的工具。舉例而言，網頁視圖通常用於查看細微變更，而對於更大的變更，我習慣於使用 vimdiff 或 Meld 在本地瀏覽。

評審意見可以被添加到整個修改中，也可以添加到擬議的變更的個別行中。一些項目限制了行的最大長度，即硬換行，或者一行一句，以使得向文本的特定的部分添加註釋更加容易。可以添加進一步的修改與評論，直到審查過程結束，修改被接受。由於拉取請求在項目倉庫以隊列形式展示，這是一種很好的方式，可以展示目前正在進行的任務以及需要進行檢查操作的任務。diff 工具使得評審人員更方便地添加他們的思考。尤其是你在與技術受眾工作時，你可以通過他們日常使用的工具獲得來自他們的評論。

持續集成與部署

以純文本形式提供你的文檔的源代碼有很多益處，你可以輕易找到每一個需要修改的位置，你可以使用現有的諸如 wc、grep 或 tree 之類的工具，來處理潛在的大型文檔集。當你將這些與源代碼管理平台結合起來之後，你可能獲得更多的可用工具，並且它們都是開源的。

另一個工作流程上的巨大提升是持續部署的能力。簡單來說，這意味著，每當一個拉取請求被合併到主項目中，項目可以直接自動化部署到位。如果這個變更足夠好，就可以放進項目中，它也足夠好到可以在放到文檔網站上幫助你的讀者。典型情況下，持續部署是配置在一台單獨的自動化伺服器上的，比如 Jenkins 或者 Git 鉤子。不論哪種方式，基於文本的標記語言與文檔即代碼平台（通常是靜態網頁生成器，比如 Hugo 或 Sphinx）結合來生成文檔網站，然後自動部署。

在部署之前，同樣的自動化流程可以被用於對將要合併的拉取請求進行檢查。在一個編程項目中，通過計算機自行進行代碼檢查、代碼測試和其他的質量檢查已經習以為常。通過類似 Vale 之類的工具可以對文本進行檢查，文檔項目也可以同樣對待。你也可以添加其他的工具，比如添加一個鏈接檢查器來確保文中所有的鏈接都是有效的。

用於文檔流程的代碼工具

被工程師們熟知並喜愛的工具都是非常好的工具，它們同時也可以用於其他類型的項目中。對於文檔而言，它們提升了寶貴的效率，尤其是當你希望你的文檔與你的團隊同步推進的時候。上面討論到的所有工具都是開源的，你可以親自嘗試，也可以為大型全球團隊，亦或者介於兩者之間的團隊，部署它們。願你的成文過程和編程過程一樣順暢。

via: https://opensource.com/article/22/10/docs-as-code

作者：Lorna Mitchell 選題：lkxed 譯者：CanYellow 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive