DevOps 文檔成熟度的四個層次
為了能在軟件迭代交付周期內(nèi)按時交付優(yōu)質(zhì)的文檔，DevOps 和 DevSecOps 的文檔實踐也需要是敏捷的。這與實現(xiàn) DevOps 類似，只是更偏向自動化和敏捷的內(nèi)容處理方法。如果文檔現(xiàn)在才進入你的機構(gòu)的 DevOps 討論，那么是時候讓文檔實踐追上 DevOps 的步伐了。
下面是 DevOps 文檔成熟度的四個層次：
第一層：臨時且孤立
在最低一級成熟度（最不成熟），文檔編制工作沒有和 DevOps 開發(fā)對齊。開發(fā)團隊和文檔團隊按照各自的路線開展工作，常常導(dǎo)致文檔落后于開發(fā)。在競爭激烈的“云”世界里，因為文檔問題而推遲產(chǎn)品發(fā)布是不可接受的。
人員
這個階段的文檔編制人員還沒有擺脫傳統(tǒng)的工作方式。技術(shù)寫作technical writer人員隸屬于一個中心化的單獨團隊，與開發(fā)團隊是脫節(jié)的。技術(shù)寫作組和開發(fā)團隊之間的鴻可能是由多方面原因造成的：
- 造成團隊分裂和孤立的公司政治
- 團隊只是將技術(shù)文檔視為項目驗收清單上的檢查項，而不是推動項目成功的資產(chǎn)
- 事后才雇傭技術(shù)寫作人員
- 技術(shù)寫作的優(yōu)先級與開發(fā)團隊的實際情況不匹配
這個階段，另一個在人員配置上的挑戰(zhàn)是如何“界定工作完成”。剛接觸敏捷實踐的技術(shù)寫作可能難以適應(yīng) CI/CD 工具鏈和流程。
文檔工具和流程
這個階段的技術(shù)寫作仍習(xí)慣于使用傳統(tǒng)的辦公工具，比如辦公套件和布局程序。這些工具不夠敏捷，沒有版本控制和內(nèi)容管理的要求。它們無法與 DevOps 工具鏈高效集成，不能支撐快速開發(fā)。在這個成熟度，技術(shù)寫作仍然參照遺留的模板和流程。
成果
這個級別交付的文檔可能是過時的，甚至缺乏技術(shù)準(zhǔn)確性的。如果開發(fā)團隊以 DevOps 的速度推進工作，而技術(shù)文檔編制卻遵循傳統(tǒng)的非敏捷流程（使用專有的工具和交付格式），這就很難讓文檔迭代速度并跟上應(yīng)用程序的變化。
第二層：實驗和試點
DevOps 文檔成熟度的第二層是實驗/試驗階段。這個階段是 DevOps 團隊主管和技術(shù)寫作采取行動打造更敏捷的文檔實踐和工具的第一步。
理想的情況下，這些實驗是相關(guān)方stakeholder支持的試點項目的一部分。他們能夠從文檔交付流程的改善以及其與 DevOps 實踐的集成中獲益。
人員
本階段的人員可能來自以下三種形式：
- 有遠(yuǎn)見的技術(shù)寫作為了更好地完成工作，用自己的時間來實驗更敏捷的工具。并且向領(lǐng)導(dǎo)層提出更敏捷的文檔編制過程的想法。
- DevOps 負(fù)責(zé)人或工程師試用 Hugo 和 Jekyll 等工具，并將這些工具集成到 CI/CD 流水線中。然后 DevOps 小組教授技術(shù)寫作如何使用它們。
- 團隊引入了第三方承包商或顧問，他們在 DevOps 文檔工具方面具有專業(yè)知識，并且了解文檔工具適合嵌入到 CI/CD 工具鏈和 DevOps 生命周期的位置。
文檔工具和實踐
Hugo 和 Jekyll 是本階段開始出現(xiàn)的工具。在這個階段也出現(xiàn)新的內(nèi)容策略和技術(shù)寫作方法。
成果
實驗試點階段理想的成果應(yīng)該能夠“落地并推廣land and expand”。也就是說其它項目組也可以將其付諸實踐。
這個階段的實驗也包括內(nèi)容策略和發(fā)布流程上的根本性變化。其它非試點項目組的技術(shù)寫作可以學(xué)習(xí)和使用它們。
試點帶來的另一個可能的產(chǎn)出是 技術(shù)寫作招聘流程 的變化。你需要針對 DevOps 和你新引入的文檔工具對內(nèi)部編寫人員進行培訓(xùn)。
新的文檔工具和流程是此階段的關(guān)鍵成果，你需要通過演示、狀態(tài)報告和內(nèi)部案例研究等方式，將這一成果推給領(lǐng)導(dǎo)層、相關(guān)方和其它團隊。
第三層：部分自動化和擴展
DevOps 文檔成熟度的第三層（部分自動化和擴展）就是“落地并推廣”的進一步行動。在這個階段，其它 DevOps 團隊借用試點項目中產(chǎn)生的 DevOps 文檔工具和流程，吸取其中的經(jīng)驗教訓(xùn)。
人員
在這個成熟度，技術(shù)寫作和 DevOps 團隊開始更緊密的協(xié)作。招聘新的技術(shù)寫作主要關(guān)注具有 DevOps 環(huán)境經(jīng)驗的人選。
工具和文檔實踐
技術(shù)寫作開始從拋棄傳統(tǒng)的工具和流程，轉(zhuǎn)到更敏捷的文檔工具上，比如：
- docToolchain
- Docbook
- Hugo
- Jekyll
在這個成熟度，技術(shù)寫作也負(fù)責(zé)調(diào)整遺留的文檔實踐。
成果
DevOps 文檔工具和實踐超越試點項目，成為標(biāo)準(zhǔn)實踐。在這個成熟度，隨著新團隊使用新的文檔工具和流程，持續(xù)學(xué)習(xí)是必不可少的。
第四層：完全采用
在最高一級的 DevOps 文檔成熟度（完全采用且自動化）所有工具、實踐和流程已經(jīng)到位，以支持將文檔為項目中的高優(yōu)先級事項。要達(dá)到這一成熟度，需要不斷實驗、迭代和團隊協(xié)作。
人員
完全自動化使 DevOps 團隊與技術(shù)寫作之間的協(xié)作更緊密。這一階段的標(biāo)志是，技術(shù)寫作牢牢地融入到項目團隊的工作流程中。文檔工具的維護工作由一些大型企業(yè)負(fù)責(zé)，它們擁有專職維護 DevOps 工具鏈的工程師。
文檔工具和實踐
在這個成熟度，技術(shù)寫作統(tǒng)一采用 Markdown 語言和自動化工具。
成果
本階段的成果是一套完整的工具和實踐，它們支持自動化在線文檔發(fā)布。技術(shù)寫作者可以按需發(fā)布和重新發(fā)布文檔，以支持迭代開發(fā)流程。
持續(xù)學(xué)習(xí)是這個階段的另一項成果。技術(shù)寫作和工具鏈維護者尋找改進自動化和流程的方法，以幫助文檔實踐。
總結(jié)
提升 DevOps 文檔成熟度的過程跟達(dá)到 DevOps 或 DevSecOps 成熟化的歷程是類似的。我希望行業(yè)能夠?qū)⒏`活的文檔實踐和工具作為公司推進 DevOps 進程中的一個部分。提高 DevOps 文檔成熟度應(yīng)該作整體 DevOps 成熟化甚至 DevOps 到 DevSecOps 轉(zhuǎn)型的一部分。
