很多工程師與手工藝者都對他們使用的工具有特別的要求。為了順利的完成工作，你需要最好的工具和使用它們的技巧。軟件開發(fā)中最好的工具在應(yīng)用到其他的數(shù)字創(chuàng)作領(lǐng)域中也可以是很強(qiáng)大的。??文檔即代碼??Docs as Code

文本格式與源文件控制

從傳統(tǒng)的寫作平臺切換到文檔即代碼方式時(shí)，最主要的調(diào)整是將寫作內(nèi)容保存在基于文本的標(biāo)記格式中。這一轉(zhuǎn)變使得基于純文本的工具都適用于文檔寫作。無論你選擇 ??DocBook??、??Markdown?? 或者其他的標(biāo)記語言，從只使用一種工具到使用一種標(biāo)準(zhǔn)格式配合多種工具是一種巨大的轉(zhuǎn)變。

找到支持你的工作流程的工具是非常重要的。很多開發(fā)者在文檔即代碼項(xiàng)目中使用他們的 ??代碼編輯器??。因?yàn)樗麄円呀?jīng)是這些工具的高階用戶，一切都很順利。而找到適合團(tuán)隊(duì)里其他專業(yè)人員，比如技術(shù)撰稿、編輯、信息架構(gòu)師和文檔產(chǎn)品責(zé)任人的工具可能需要一番努力。這里有一些選項(xiàng)可供參考：

• 各種??優(yōu)秀的 Markdown 編輯器?? 之一
• 附帶良好的預(yù)覽工具的代碼編輯器可能更適合非程序員
• 流行的 Git 托管服務(wù)的網(wǎng)頁界面尤其適用于偶爾有需要的貢獻(xiàn)者

一旦內(nèi)容以標(biāo)記語言的格式安全地保存，就可以使用 ??Git?? 這樣的版本控制進(jìn)行管理。Git 相比大多數(shù)文檔平臺具有更多的功能：

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

源代碼管理有很多優(yōu)點(diǎn)。但要記住，如果你準(zhǔn)備入門源代碼管理，它有一定的學(xué)習(xí)曲線。這是一些有助于撰寫者入門的優(yōu)秀的 ??學(xué)習(xí)資源?? 和 ??文章??。你也可以讓具有好奇心的文檔撰寫者自行尋找對他們有用的學(xué)習(xí)材料，而不是請你的工程師來培訓(xùn)他們。（問我是怎么學(xué)會的？ —— 當(dāng)然是通過艱苦的方式?。?/p>

拉取請求和評審循環(huán)

所有的源代碼管理平臺都圍繞 拉取請求Pull Request

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

評審意見可以被添加到整個修改中，也可以添加到擬議的變更的個別行中。一些項(xiàng)目限制了行的最大長度，即硬換行，或者一行一句，以使得向文本的特定的部分添加注釋更加容易。可以添加進(jìn)一步的修改與評論，直到審查過程結(jié)束，修改被接受。由于拉取請求在項(xiàng)目倉庫以隊(duì)列形式展示，這是一種很好的方式，可以展示目前正在進(jìn)行的任務(wù)以及需要進(jìn)行檢查操作的任務(wù)。??diff?? 工具使得評審人員更方便地添加他們的思考。尤其是你在與技術(shù)受眾工作時(shí)，你可以通過他們?nèi)粘Ｊ褂玫墓ぞ攉@得來自他們的評論。

持續(xù)集成與部署

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

另一個工作流程上的巨大提升是持續(xù)部署的能力。簡單來說，這意味著，每當(dāng)一個拉取請求被合并到主項(xiàng)目中，項(xiàng)目可以直接自動化部署到位。如果這個變更足夠好，就可以放進(jìn)項(xiàng)目中，它也足夠好到可以在放到文檔網(wǎng)站上幫助你的讀者。典型情況下，持續(xù)部署是配置在一臺單獨(dú)的自動化服務(wù)器上的，比如 ??Jenkins?? 或者 ??Git 鉤子??。不論哪種方式，基于文本的標(biāo)記語言與文檔即代碼平臺（通常是靜態(tài)網(wǎng)頁生成器，比如 ??Hugo?? 或 ??Sphinx??）結(jié)合來生成文檔網(wǎng)站，然后自動部署。

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

用于文檔流程的代碼工具

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