文檔寫作的 DevOps 指南

DevOps 正在挑戰技術文檔的規範，這在 IT 歷史上是前所未有的。從自動化到提高交付速度，再到拆除瀑布式軟體開發生命周期模型，這意味著業務和技術文檔寫作的理念需要做出巨大改變。

以下是 DevOps 對技術文檔寫作不同方面的影響。

技術寫手的角色變化

技術寫手必須適應 DevOps。好消息是，許多技術寫手已經加入到開發團隊中，並且擁有合作關係和不斷增長的產品知識的技術寫手很具優勢。

但是如果一個技術寫手習慣於獨立工作，並依賴於領域專家的草稿作為文檔的基礎，那麼就需要做一些調整。

進行一些投資，以確保文檔和其他與項目有關的內容開發工作獲得所需的工具、結構和支持。從改變 技術寫手聘用方式 開始。以 DevOps 的速度 編寫文檔需要重新思考內容規劃，並打破 DevOps 團隊和支持項目的技術寫手之間長期存在的隔閡。

DevOps 使開發團隊擺脫了傳統文檔實踐的束縛。首先，文檔 完成的定義 必須改變。一些企業的文化使技術寫手成為軟體開發的被動參與者。DevOps 提出了新的要求：隨著 DevOps 文化的轉變，技術寫手的角色也應發生變化。技術寫手需要（且必須適應）DevOps 提供的透明度。他們必須融入 DevOps 團隊。取決於組織如何塑造這個角色，將技術寫手帶入團隊可能會帶來技能上的挑戰。

文檔標準、方法和規格

雖然 DevOps 還沒有影響到技術文檔本身，但開源社區已經加強了對應用編程介面（API）文檔的幫助，已經有不同規模的企業的 DevOps 團隊正在使用這些文檔。

用於記錄 API 的開源規範和工具是個非常值得關注的領域。我想這是由於 谷歌文檔季 的影響，它使開源軟體項目能夠獲得專業的技術寫作人才來解決他們最關鍵的文檔項目。

開源 API 屬於 DevOps 文檔討論的一部分。雲原生應用集成需求的重要性正在上升。OpenAPI 規範（一個定義和記錄 API 的開放標準）是在 DevOps 環境下 API 文檔的良好資源。然而，該規範會導致文檔的創建和更新過程變得很費時，這使其飽受批評。

曾經也有短暫嘗試過創建 持續文檔 Continuous Documentation ，並且還有一個來自 CA（現在的 Broadcom）的創建 DocOps 框架的運動。然而，DocOps 從來沒有作為一個行業運動流行起來。

DevOps 文檔標準的現狀意味著 DevOps 團隊（包括技術寫手）需要在項目的最初階段就開始創建文檔。要做到這一點，你需要把文檔作為一個敏捷故事和（同樣重要的）管理期望，並且把它與年度績效評估放在一起執行。

文檔工具

文檔的編寫應該以一種所有團隊成員都可以使用的格式或平台在線進行。MediaWiki、DokuWiki、TikiWiki 和其他 開源維基 為 DevOps 團隊提供了一個編寫和維護文檔的中央倉庫。

讓團隊選擇他們的維基平台，就像讓他們選擇他們的其他持續集成/持續開發（CI/CD）工具鏈一樣。開源維基強大之處在於其可擴展性。例如，DokuWiki 包括一系列的擴展，你可以通過安裝這些擴展來創建一個符合你的 DevOps 團隊的創作要求的平台。

如果你有足夠的野心來加強你的團隊的編寫和協作能力，Nextcloud（一個開源的雲協作套件）是一個讓你的 DevOps 團隊上網並給他們提供編寫文檔所需工具的選擇。

DevOps 最佳實踐

文檔在 DevOps 轉型中也發揮著作用。例如，你會想要記錄組織從 DevOps 實現效率和流程增益的最佳實踐，這些信息太重要了，不能靠著 DevOps 團中之間口耳相傳。如果你所在的組織有多個 DevOps 團隊，那麼文檔就是統一的力量，它可以促進最佳實踐的標準化，並設置了衡量代碼質量的基準指標。

一般情況下，開發人員承擔了記錄 DevOps 實踐的工作。即使他們的組織有技術寫手，他們也可能跨開發團隊工作。因此，開發人員和系統管理員能夠捕捉、記錄和交流他們的最佳實踐是很重要的。這裡有一些朝正確的方向發展的提示：

• 提前花時間為 DevOps 最佳實踐創建標準模板。不要陷入複製在線模板的陷阱。採訪利益相關者和團隊來創建一個符合團隊需求的模板。
• 尋找一些創造性的信息收集的方法，例如記錄團隊會議和使用聊天系統日誌來作為文檔的基礎。
• 建立一個用於發布最佳實踐的維基。使用維基可以跟蹤編輯和更新。這樣的平台可以幫助團隊在最佳實踐發生變化時進行更新和維護。

當在構建 CI/CD 工具鏈時記錄依賴關係是非常明智的。尤其是當加入新的團隊成員時，你會發現這些記錄非常有用，另外當團隊成員忘記一些事情時，這也是一種保險。

最後，自動化對 DevOps 利益相關者和從業者都很有吸引力。在自動化中斷之前，一切都很有趣。擁有自動化運行手冊、管理指南和其他內容的文檔（並且是最新的）意味著無論何時發生故障，員工都可以讓自動化重新工作。

最後一些想法

DevOps 對於技術文檔來說是一個積極的因素。它將內容開發納入 DevOps 生命周期，並打破組織文化中開發人員和技術作者之間的隔閡。在沒有技術寫手的情況下，團隊就可以使用工具來加快文檔創作的速度，以與 DevOps 的速度相匹配。

你的組織將如何把文檔加入到 DevOps 生命周期？請在評論區分享你的經驗。

via: https://opensource.com/article/21/3/devops-documentation

作者：Will Kelly 選題：lujun9972 譯者：Veryzzj 校對：校對者ID

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

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