引言
通常情況下，正式的文檔（如源代碼文檔、系統(tǒng)需求與設計文檔，或者各類用戶文檔）會被開發(fā)團隊忽視得徹徹底底，而 DevOps 中關于流程與文檔的理念可以幫助緩解這個問題。軟件文檔通常分為以下幾類：代碼，需求，設計、系統(tǒng)與用戶文檔。
文檔經常會被忽略的原因之一在于，如果不能與所依賴的開發(fā)工具（如版本控制、問題追蹤工具、wiki 及源代碼）相匹配，標準文檔工具及流程反而會對開發(fā)團隊造成妨礙，并拖慢開發(fā)速度①。
本文探討了文檔化所遇到的3個主要挑戰(zhàn)：流程、注釋源代碼以及系統(tǒng)文檔；同時解釋了以 DevOps 為基礎的文檔，可以通過怎樣的方式使所有相關人等獲利，即訪問通用、可信的信息源，并查看項目的細節(jié)。
問題流程
創(chuàng)建、維護用戶文檔與系統(tǒng)文檔時，操作人員通常會使用笨重的二進制文檔（比如 *.docx）。一般來說，在文檔協作體系中，還包括一長串來來回回的電郵，或者網絡共享的文件，人們使用這些形式相互傳送文檔的更新版本。
此外，專用格式（ *.docx 與生成的 PDF）往往會因為跨系統(tǒng)操作而產生不一致，從而在跨團隊合作時，常常因為工作環(huán)境不同而產生數據損毀。
將二進制文件存儲在版本控制系統(tǒng)中是一種解決辦法，但管理多個版本的二進制文件仍舊極具挑戰(zhàn)。采用自動化文檔，并將它們集成在軟件開發(fā)生命周期（SDLC）中同樣存在許多問題：
隨著項目的進程，這些文檔經常會更新地越來越少，或者被完全廢棄。
文檔數量非常之多，也是不恰當的?；蛘哒f，每支團隊都應當在豐富與簡單之間找到平衡。
文檔代碼“不分家”
在談及文檔這個話題時，區(qū)分客觀信息與主觀加工過的材料非常重要：
信息指的是數據或者記錄的來源；而主觀材料則是通過有序地組織信息而產生的可用終端產品，這種信息是可以被讀者閱讀的，可能包括系統(tǒng)需求文檔、設計文檔、狀態(tài)報告等等。
信息可以在不同的源中維護，比如在問題追蹤器、wiki 以及代碼儲存庫中；同時，信息應當存儲在實際中人們與數據交互或執(zhí)行的地方。比如在尋找描述某個具體功能的文檔時，該文檔應就應該存儲在相關功能所在之處：代碼旁。
如果功能文檔沒有與代碼存在一起，一旦功能有所改變，那么工程師不止需要更新代碼，還要尋找代碼相關的文檔以便更新。文檔匱乏會拖慢開發(fā)的進度，工程師需要維護、管理并利用好這些信息。
在所有信息存好之后，我們就可以通過工具來撰寫大家能夠閱讀并理解的文檔，來為讀者提供信息：
這些撰寫的材料一旦生成，就不再更改，以作參考信息；生成文檔的流程是獲取最新數據的方法。將文檔材料作為網頁上傳是保存這類文檔的一個完美手段，因為網頁顯示的總是最新版本的文檔。
源代碼
長期以來，注釋代碼的能力都屬于編程高級實踐的一部分。在過去十年間，人們?yōu)榱烁倪M文檔體驗，為各種語言開發(fā)了不少工具。這些工具允許開發(fā)者將相關信息歸檔，協助開發(fā)人員理解代碼。
下面提到的一些工具也允許程序員在自己的文檔中將測試以可讀的方式添加進去。這樣，很拽的地方在于：
編譯代碼時，文檔中的測試會自動運行，如果程序員修改了代碼，卻沒有更新文檔的話，build 就會失敗。
持續(xù)集成環(huán)境②的快速反饋可以協助程序員，確保其遵守正確的文檔策略。
下面的工具是樣板庫，可以直接從源代碼注釋中生成可讀的文檔材料。
Ruby: RDoc③
Python: Sphinx④
Java: Javadoc⑤
Ruby, Java, .NET, Flex: Cucumber⑥
C++等: Doxygen⑦
通常管理者可能都不清楚應該對工程師要求什么樣的文檔。筆者就不止一次收到過這樣的需求——將每一行代碼的功能寫在注釋里⑧。
管理者需要了解：這類文檔對程序員來說任務繁重，很快就能摧毀任何程序員在合理的時間內交付有商業(yè)價值內容的能力。
而在 DevOps 中，一切都應該被自動化⑨，并找出可理解與簡單化之間的平衡點。
建議：堅持「新對象應該進行文檔描述」這個思想，以將所有新對象“自動文檔化”，這可能是幫助程序員在代碼中添加注釋的好辦法。
但是，如果沒有文檔也沒什么影響的話（比如引起 build 失?。銜l(fā)現一切對象都處在未歸檔的情況下（或者用占位符信息錯誤歸檔），從而導致返工，需要重新整理欠下的⑩一大堆文檔。
開發(fā)人員可以使用上面列出的工具來驗證文檔是否過期，從實踐效果來看也很不錯。
如果想在一個生命周期的結尾對該項目進行記錄的話，應當在重要環(huán)節(jié)將工具打開。從項目一開始，在編寫文檔時著眼于每一個最小可用的產品?：記錄實際情況，而不是得出解決方案的過程。
系統(tǒng)、設計和用戶文檔
撰寫系統(tǒng)、設計與用戶文檔的工具，往往沒有注釋源代碼的工具那樣種類豐富。很多時候，公司需要從頭開發(fā)自己的通用流程與基礎架構。
在近期的一篇博文?中，Red Hat 的高級技術文檔撰寫者Mikey Ariel?倡導使用持續(xù)集成與單元測試文檔：
在該文中，Ariel 將這一過程描述為：能夠測試文檔是否遵守指南（比如，公司使用的是 backend 還是 back-end）以及語法（利用接口使用像是Hemingway?或After the Deadline?之類的工具）。
使用單元測試文檔的理念可以確保公司各個部門之間文檔的標準化。
在 DevOpsDays NYC2015 關于文檔的討論中，來自 Etsy? 的 Mike Rembestsy? 將他們的流程描述為「對數據中心的網絡基礎結構進行動態(tài)記錄」：
Etsy 使用 Chef 來更新他們的基礎結構，同時 Chef 腳本動態(tài)地更新Nagios?，監(jiān)視實例與動態(tài)編輯、發(fā)布網絡圖。
通過在文檔中使用 DevOps 的手段，Etsy 的工程師實現了更新文檔的過程自動化，這樣在他們完成工作的時候順便就完成了這一過程。這些理念與實踐在保證文檔精準的同時，也反映了系統(tǒng)的當前狀態(tài)。
我們的建議是：將文檔當作源代碼管理，使得信息版本化，并允許個人有能力維護或將較小的數據來源與各類文檔材料自動合并。
處理可控數據可以通過有效利用安排，將降低上下文切換所帶來的不利影響?。
切換到 DevOps 文檔流程與工作流程時，需要轉換思想，考慮什么工具對生成文檔最為必要。團隊在信息生成時越自動化，或者在促進信息管理時越有效，文檔的質量與可用性也就越高。
最終，以 DevOps 為基礎的文檔就能夠允許所有利益相關者訪問一份通用、可信的信息源，來了解項目詳情了。
① http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm
② http://insights.sei.cmu.edu/post.cfm/continuous-integration-in-devops
③ http://rdoc.sourceforge.net/
④ http://sphinx-doc.org/
⑤ http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html
⑥ https://cucumber.io/
⑦ https://en.wikipedia.org/wiki/Doxygen
⑧ http://programmers.stackexchange.com/questions/106202/my-boss-wants-a-narrated-line-by-line-english-explanation-of-our-code
⑨ http://insights.sei.cmu.edu/post.cfm/generalized-model-automated-devops-153
⑩ http://insights.sei.cmu.edu/post.cfm/field-study-technical-debt-208
? http://leanstack.com/minimum-viable-product/
? https://opensource.com/business/15/7/documentation-devops
? https://twitter.com/thatdocslady
? http://www.hemingwayapp.com/
? http://www.afterthedeadline.com/
? https://www.etsy.com/
? https://twitter.com/mrembetsy
? https://www.nagios.org/
? https://blog.sei.cmu.edu/post.cfm/addressing-detrimental-effects-context-switching-devops-064
如何一起愉快地發(fā)展
第三十六屆CIO班招生
國際CIO認證培訓
首席數據官（CDO）認證培訓
責編：content
免責聲明：本網站（http://www.www.gypb.net/）內容主要來自原創(chuàng)、合作媒體供稿和第三方投稿，凡在本網站出現的信息，均僅供參考。本網站將盡力確保所提供信息的準確性及可靠性，但不保證有關資料的準確性及可靠性，讀者在使用前請進一步核實，并對任何自主決定的行為負責。本網站對有關資料所引致的錯誤、不確或遺漏，概不負任何法律責任。
本網站刊載的所有內容（包括但不僅限文字、圖片、LOGO、音頻、視頻、軟件、程序等）版權歸原作者所有。任何單位或個人認為本網站中的內容可能涉嫌侵犯其知識產權或存在不實內容時，請及時通知本站，予以刪除。
搶沙發(fā)
