DevOps 文檔成熟度的四個層次

提升 DevOps 文檔成熟度的過程與達到 DevOps 或 DevSecOps 成熟化的歷程是類似的。

為了能在軟體迭代交付周期內按時交付優質的文檔，DevOps 和 DevSecOps 的文檔實踐也需要是敏捷的。這與實現 DevOps 類似，只是更偏向自動化和敏捷的內容處理方法。如果文檔現在才進入你的機構的 DevOps 討論，那麼是時候讓文檔實踐追上 DevOps 的步伐了。

下面是 DevOps 文檔成熟度的四個層次：

第一層：臨時且孤立

在最低一級成熟度（最不成熟），文檔編製工作沒有和 DevOps 開發對齊。開發團隊和文檔團隊按照各自的路線開展工作，常常導致文檔落後於開發。在競爭激烈的「雲」世界裡，因為文檔問題而推遲產品發布是不可接受的。

人員

這個階段的文檔編製人員還沒有擺脫傳統的工作方式。 技術寫作 technical writer 人員隸屬於一個中心化的單獨團隊，與開發團隊是脫節的。技術寫作組和開發團隊之間的鴻可能是由多方面原因造成的：

• 造成團隊分裂和孤立的公司政治
• 團隊只是將技術文檔視為項目驗收清單上的檢查項，而不是推動項目成功的資產
• 事後才僱傭技術寫作人員
• 技術寫作的優先順序與開發團隊的實際情況不匹配

這個階段，另一個在人員配置上的挑戰是如何「界定工作完成」。剛接觸敏捷實踐的技術寫作可能難以適應 CI/CD 工具鏈和流程。

文檔工具和流程

這個階段的技術寫作仍習慣於使用傳統的辦公工具，比如辦公套件和布局程序。這些工具不夠敏捷，沒有版本控制和內容管理的要求。它們無法與 DevOps 工具鏈高效集成，不能支撐快速開發。在這個成熟度，技術寫作仍然參照遺留的模板和流程。

成果

這個級別交付的文檔可能是過時的，甚至缺乏技術準確性的。如果開發團隊以 DevOps 的速度推進工作，而技術文檔編製卻遵循傳統的非敏捷流程（使用專有的工具和交付格式），這就很難讓文檔迭代速度並跟上應用程序的變化。

第二層：實驗和試點

DevOps 文檔成熟度的第二層是實驗/試驗階段。這個階段是 DevOps 團隊主管和技術寫作採取行動打造更敏捷的文檔實踐和工具的第一步。

理想的情況下，這些實驗是 相關方 stakeholder 支持的試點項目的一部分。他們能夠從文檔交付流程的改善以及其與 DevOps 實踐的集成中獲益。

人員

本階段的人員可能來自以下三種形式：

1. 有遠見的技術寫作為了更好地完成工作，用自己的時間來實驗更敏捷的工具。並且向領導層提出更敏捷的文檔編製過程的想法。
2. DevOps 負責人或工程師試用 Hugo 和 Jekyll 等工具，並將這些工具集成到 CI/CD 流水線中。然後 DevOps 小組教授技術寫作如何使用它們。
3. 團隊引入了第三方承包商或顧問，他們在 DevOps 文檔工具方面具有專業知識，並且了解文檔工具適合嵌入到 CI/CD 工具鏈和 DevOps 生命周期的位置。

文檔工具和實踐

Hugo 和 Jekyll 是本階段開始出現的工具。在這個階段也出現新的內容策略和技術寫作方法。

成果

實驗試點階段理想的成果應該能夠「 落地並推廣 land and expand 」。也就是說其它項目組也可以將其付諸實踐。

這個階段的實驗也包括內容策略和發布流程上的根本性變化。其它非試點項目組的技術寫作可以學習和使用它們。

試點帶來的另一個可能的產出是 技術寫作招聘流程 的變化。你需要針對 DevOps 和你新引入的文檔工具對內部編寫人員進行培訓。

新的文檔工具和流程是此階段的關鍵成果，你需要通過演示、狀態報告和內部案例研究等方式，將這一成果推給領導層、相關方和其它團隊。

第三層：部分自動化和擴展

DevOps 文檔成熟度的第三層（部分自動化和擴展）就是「落地並推廣」的進一步行動。在這個階段，其它 DevOps 團隊借用試點項目中產生的 DevOps 文檔工具和流程，吸取其中的經驗教訓。

人員

在這個成熟度，技術寫作和 DevOps 團隊開始更緊密的協作。招聘新的技術寫作主要關注具有 DevOps 環境經驗的人選。

工具和文檔實踐

技術寫作開始從拋棄傳統的工具和流程，轉到更敏捷的文檔工具上，比如：

• docToolchain
• Docbook
• Hugo
• Jekyll

在這個成熟度，技術寫作也負責調整遺留的文檔實踐。

成果

DevOps 文檔工具和實踐超越試點項目，成為標準實踐。在這個成熟度，隨著新團隊使用新的文檔工具和流程，持續學習是必不可少的。

第四層：完全採用

在最高一級的 DevOps 文檔成熟度（完全採用且自動化）所有工具、實踐和流程已經到位，以支持將文檔為項目中的高優先順序事項。要達到這一成熟度，需要不斷實驗、迭代和團隊協作。

人員

完全自動化使 DevOps 團隊與技術寫作之間的協作更緊密。這一階段的標誌是，技術寫作牢牢地融入到項目團隊的工作流程中。文檔工具的維護工作由一些大型企業負責，它們擁有專職維護 DevOps 工具鏈的工程師。

文檔工具和實踐

在這個成熟度，技術寫作統一採用 Markdown 語言和自動化工具。

成果

本階段的成果是一套完整的工具和實踐，它們支持自動化在線文檔發布。技術寫作者可以按需發布和重新發布文檔，以支持迭代開發流程。

持續學習是這個階段的另一項成果。技術寫作和工具鏈維護者尋找改進自動化和流程的方法，以幫助文檔實踐。

總結

提升 DevOps 文檔成熟度的過程跟達到 DevOps 或 DevSecOps 成熟化的歷程是類似的。我希望行業能夠將更靈活的文檔實踐和工具作為公司推進 DevOps 進程中的一個部分。提高 DevOps 文檔成熟度應該作整體 DevOps 成熟化甚至 DevOps 到 DevSecOps 轉型的一部分。

（題圖：MJ/154429b7-bdfc-4b34-9a81-55d9fe33ab07）

via: https://opensource.com/article/22/2/devops-documentation-maturity

作者：Will Kelly 選題：lujun9972 譯者：toknow-gh 校對：wxy

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

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