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