面向完整價值交付的文檔DevOps應用研究*

金澤鋒,張佑文,葉文華,張 賀,邵 棟

1(中興通訊,江蘇 南京 210012)

2(計算機軟件新技術國家重點實驗室(南京大學),江蘇 南京 210023)

IT 調研與咨詢服務公司Gartner 2015 的調查報告顯示,全球前2 000 家大型軟件公司中25%使用DevOps方式作為公司主流方式交付軟件的模式[1].全球云管理平臺領導者RightScale 公司調查報告也顯示,DevOps 已成為研發基于云的應用程序的默認方法了,其接受度從2015 年的66%增至2017 年的78%,而其中,大型企業的采用率更高達84%,且以其作為主流軟件交付模式的占到30%[2,3].

軟件產品不僅僅包含可執行程序和支撐數據(本文統稱為軟件版本),還含有配套的文檔集合(以下簡稱產品文檔).特別是在大規模系統軟件產品(以下簡稱“系統軟件”)研發和交付領域,產品文檔還占有非常重要的地位,探索相關問題的解決方案的需求也更為迫切[4].本文的文檔DevOps 即是在業界這個方向上的實踐與總結.

系統軟件是一類為解決復雜問題或為服務龐大客戶群所開發的軟件,往往由大型企業、組織和政府所最終擁有,對軟件產品的要求高.同時,大規模系統軟件的研發和最后的運營維護往往由不同團隊完成,例如電信產品由少數電信設備商研發交付,卻由運營商或第三方來承擔開通、運營、維護和優化.這個過程中,運維人員的產品知識一般來源于設備商提供的產品相關文檔,所以,在系統軟件交付的同時,產品文檔也作為重要交付物需要交付給客戶.因此,在產品文檔開發方面會有如下幾個重要挑戰.

(1)文檔內容覆蓋要全面且系統詳盡:交付運營的特性需要進行大范圍的產品知識轉移,轉移過程無法長期依靠研發專家的人工支持,而且高端客戶往往都是學習型組織,對大規模軟件系統的了解非常深入,需要大量對細節的描述.這些必須依賴于系統、詳盡的產品文檔,便于規模化知識的轉移.

(2)軟件和文檔的高質量要求:通常,大規模軟件系統的最終用戶(例如ISP 的客戶)的數量非常龐大,倘若出現故障,一般影響面都會很大,這就要求軟件系統本身應該具備高可靠性,同時運維人員的操作需嚴格遵循操作說明執行,以便提供穩定的運維服務.這意味著不僅交付的軟件系統應該包含盡可能少的缺陷,而且相應的產品文檔中的內容應該完全和產品保持一樣的高質量要求,同時必須和軟件產品保持完全一致.例如,文檔內容中通常未明確說明其描述的軟件版本,讀者不清楚所提供的信息是否是最新的,而文檔描述的內容在不同版本之間往往是有明顯差異的[5].

(3)要完整表述高復雜的系統,文檔架構也必然復雜:通常交付給客戶的產品錯綜復雜,而且使用人員群體龐大、個體差異明顯,這兩個方面最終導致產品文檔內容通常非常龐大而且復雜.不同產品間的文檔還需要關注相互的引用要準確,表述要規范、清晰.

綜上所述,產品配套文檔應具有以下“四性”.

(1)準確性:產品文檔描述的內容,與實際設備的內外部特征和使用方法保持一致,并反映產品的最新更新.

(2)完整性:產品文檔中能夠系統、詳盡地描述產品所提供的全部功能,并包含產品開通、運營、維護和優化等各類活動涉及到的產品相關知識.

(3)及時性:產品文檔需要在使用時間前完全準備好,用戶可以在需要的時候快速獲取到產品的配套文檔.

(4)可用性:文檔結構清晰,關鍵內容突出,步驟詳細,可以指導目標用戶高效地完成工作.同時,在各部分文件間的內容描述是規范的,用戶體驗是一致的.

實際系統軟件交付過程中,產品文檔大量存在著內容不準確、不一致[6],內容缺失[7,8],交付嚴重滯后[9,10]的現象,與用戶對文檔的要求存在較大的差距.通過產業界和學術界的合作,參考DevOps 的理念、實踐和工具,我們設計了一種新的文檔開發模式“文檔DevOps”和配套的文檔DevOps 平臺“iDOC”來解決以上問題.

文檔DevOps 首先將文檔代碼化,將文檔的開發過程內置到敏捷流程中,與需求開發交付過程匹配進度,并且利用文檔模板解耦內容,結合同源工具生產后續面向各類用戶的產品文檔,以實現在全程消除內容的冗余.文檔DevOps 中還借鑒CI(continuous integration,持續集成)技術,將面向文檔的質量檢查工具內置在日常的文檔編寫集成過程,做到快速反饋和質量內建.文檔DevOps 也和軟件版本的DevOps 一樣,打通了開發階段后到發布階段的反饋環,并能夠做到基于版本管理的自動化發布.

本文文檔DevOps 模式中提供了的相關的流程與實現架構,能夠讓軟件版本和產品文檔同步發布,并且利用DevOps 的優勢提升了文檔開發協作效率和產品文檔的質量.

本文工作的意義在于完善了軟件工程中關于DevOps 的完整性描述,涵蓋了版本和文檔兩類主要對象.同時,有力地支持了敏捷中價值交付的實現:用戶的價值訴求不光是軟件版本,還有產品文檔,利用敏捷迭代對客戶完整交付系統軟件具有現實意義.

1 背景介紹

1.1 問題產生

ZTE 是全球頂級的電信企業,擁有超過30 000 名研發人員,為互聯網服務提供商和電信集團提供硬件設備和大規模軟件系統.

如圖1 所示,ZTE 在2013 年前使用傳統流程(即瀑布模型)來開發和交付軟件產品,大規模系統軟件的版本交付周期平均約為9～12 個月.

Fig.1 The traditional way to deliver a version圖1 傳統產品交付模型

在傳統交付流程中,產品文檔開發往往從版本的發布測試階段開始.技術寫作者不直接參與產品研發過程,而僅是后期從事產品文檔的開發.他們所需要的產品知識是依賴于研發人員輸出的產品文檔素材或者和研發人員溝通確認來獲取必要的信息.這個串行開發過程有如下幾個缺點.

(1)導致文檔交付滯后于軟件版本,影響到產品文檔交付的及時性.系統軟件的文檔交付周期經常延遲2 個月以上.

(2)技術寫作者與研發人員通過文檔素材拋接傳遞產品知識,會嚴重影響文檔的準確性和完整性.其原因是面對研發人員提供的素材,技術寫作者在雙方知識背景偏差較大時容易產生理解偏差.時間點上,素材的溝通確認與產品功能的研發之間往往隔了幾個月,會加劇理解和溝通的難度.

(3)質量反饋周期過長,文檔開發改進慢.批量交付模式導致問題的反饋周期長,又集中在產品交付后期,交付壓力下文檔測試容易被壓縮,測試不充分,文檔準確性、完整性、可用性等方面故障泄露到用戶.當前發現的文檔問題,相應的研發人員正在忙其他需求,參與解決問題的成本高.大量文檔問題被積壓后,常依賴運動式質量提升活動解決,針對文檔開發過程的改進頻次低且沉淀不足.

2013 年在該公司內部為應對外部市場變化,針對軟件研發發起了一場敏捷變革,敏捷的軟件版本交付模式如圖2 所示.

Fig.2 The agile way to deliver a version圖2 敏捷軟件版本交付模型

研發團隊采用敏捷的迭代流程完成高頻、小批量的需求交付,并采用DevOps 進一步加快功能開發、集成和軟件版本交付的速度.與傳統產品交付模型相比,發布節奏平均縮短到1～6 個月.

但在敏捷軟件交付模型中忽略了產品文檔開發的配套改進,敏捷優秀實踐的引入讓如下問題變得更加突出.

(1)版本頻繁發布帶來配套文檔延遲的頻度變得更多了,文檔同步交付的及時性需求更加迫切.

(2)敏捷鼓勵面對面溝通,輕量級文檔導致技術寫作者的工作素材來源不足[11,12].敏捷宣言中“可以工作的軟件勝過面面俱到的文檔”[13]往往被誤解[14],軟件開發過程的內部文檔甚至被一些敏捷專家視為浪費[15],這種誤導也進一步弱化了文檔素材的及時輸出.在很多敏捷項目中,文檔變成了燙手山芋,無人愿意接手[16].

(3)敏捷鼓勵全棧工程師容易導致更為頻繁的責任變更,技術寫作者經常會遇到找不到合適的研發人員來獲取文檔相關信息的情況.

敏捷變革使得版本交付大幅提效,但產品文檔交付的及時性和效率卻遇到更大挑戰,無法同步提供產品文檔,產品文檔的開發已成為整個組織交付改進的瓶頸.

1.2 行業方案分析

在大型軟件系統的文檔開發領域,業界有兩類較為成熟的解決方案:以DITA 為代表的專業文檔編寫和發布方案和以Openstack 社區為代表的開源文檔代碼化的解決方案.這兩個方案各有適用場景和特點,分析如下.1.2.1 大型產品的專業文檔編寫和發布解決方案

DITA(darwin information typing architecture)是OASIS 技術標準,它利用XML 技術框架,構建了一套完整的用于文檔的方案.DITA 的解決方案支持模塊化寫作,定義了標準的信息模塊,如基本Topic、Concept、Task、Reference 這4 種Topic,同時,DITA 也支持定義新的信息模塊(topic)[17,18].標準化的模塊有助于分工協作寫作,也便于信息的復用,相同信息只需寫作1 次,便可應用在各類文檔中.例如一個Topic 的信息,可以同時用于“特性指導書”“用戶手冊”“聯機幫助”等不同類型文檔中.避免信息冗余,提高了信息開發效率,同時也降低了開發成本.DITA 支持內容與格式分離,基于DITA 的寫作可以實現內容與格式的分離,DITA 信息可以方便轉換為各種格式.

對于系統軟件產品團隊,一般是采用定制的DITA 商業工具,DITA 方案有兩個比較顯著的特征.

(1)面向的是專業的技術寫作者

DITA 相對比較復雜,在最新的V1.3 全集中,Topic 類型有26 種,編寫元素高達621 個,即便是在基本集中,Topic 類型有4 種Topic 類型,189 個編寫元素[19].作為一種神秘、過于復雜的語言,學習曲線比較陡峭,對應的特殊編輯工具也比較專業,主要用于供技術寫作者使用[20].由于這個原因,大量的Topic 的內容需要由規劃、研發等人員傳遞素材給技術寫作者,技術寫作者再進行加工和編寫Topic,不利于提升文檔的準確性、及時性.

OASIS 也意識到DITA 的復雜性,已經開始研究輕量級DITA(lightweight DITA,簡稱LwDITA),引入了HTML5 格式(HDITA)和MarkDown 格式(MDITA)[21].在目前開發尚未發布的DITA2.0 版本中,重點也將減少DITA 中大量未使用的特性.

(2)重在解決產品文檔間的冗余問題

DITA 方案更多地是考慮產品文檔之間的信息同源與重用,文檔的信息單元輸出與軟件系統的流程關聯性很弱,導致產品文檔開發和軟件交付中的信息單元相互缺乏支撐,而且這種弱關聯性也是文檔與軟件的不一致問題的重要來源[22].

總的來看,DITA 是比較專業和成熟的一套解決方案,在文檔與軟件的同步發布的挑戰下,該方案的弱項在于沒有考慮對敏捷模式的文檔開發支撐,即如何將文檔開發與軟件開發的人員、信息和流程的協同整合,解決它們之間的內容一致性,發布同步性等問題.

1.2.2 開源社區的文檔代碼化解決方案

以Openstack 為代表的開源社區,在開源軟件Openstack 的文檔上探索了一條大型軟件系統的文檔代碼化的解決方案[23].具有如下特征.

(1)文檔作者是開源社區的開發人員

開源社區中的軟件團隊往往缺少專業技術寫作者,是由軟件研發人員來編寫文檔內容.這種人員安排讓信息的準確性有了基礎,但要求開源文檔的編寫方式保持與軟件的開發方式相一致,我們通常稱這種方式為文檔代碼化.

開源社區文檔的讀者主要是研發人員,他們對產品文檔的準確性更加看重.文檔完整和準確與否,是開源軟件被選用的決定性因素,所以在開源社區的文檔解決方案中,比較關注產品文檔與代碼中信息的同源關系.

但開源文檔的代碼化解決方案中不涉及市場規劃、工程服務、測試、文檔活動中的人員,也不太涉及除代碼以外的同源關系管理.

(2)文檔和代碼流程統一管理

開源軟件的變更活動和發布都比較頻繁,對文檔的頻繁更新快速發布、文檔與軟件的一致性提出了更高的要求.

開源文檔開發與軟件開發基本一致:(a)目前開源社區中,大量團隊使用與代碼編寫方式非常類似的標記語言編寫產品文檔,如Markdown、reStructedText 等.(b)過程中擁有類似軟件中的編碼、檢查、構建、發布等環節,并且基本上與軟件節奏一致.(c)引入了軟件的持續集成、持續發布等實踐和自動化工具.(d)協作上,文檔和代碼都采用統一的存儲方式,例如使用Github 讓代碼和文檔在同一個repo 下,開發人員和文檔工程師均可訪問,版本控制采用與代碼相同的git 或svn 這類工具進行版本管理.流程、技術工具和內容管理上的一致,較好地保證了軟件與文檔內容的一致性和發布的及時性[24].

開源解決方案的問題在于,開源組織比較松散,難以在全局整體信息內容上進行同源與重用的設計規劃,不同人員的文檔內容可能存在一定的重復或不一致.

1.2.3 小 結

綜上對比分析可以看到,DITA 的解決方案難以確保敏捷交付模式下文檔內容的“及時性”和“正確性”.開源解決方案沒有考慮同源的設計,難以確保復雜系統文檔的“準確性”和“完整性”.

在敏捷研發模式下,為了更好地解決大型軟件系統的文檔“四性”問題,還需要探索新的解決方案.

2 文檔DevOps 方案設計

2.1 本文解決方案

為了能夠同步交付產品文檔,可以將產品文檔視為可持續交付的完整產品的有機部分、同步交付軟件和文檔.敏捷軟件模式下的版本與文檔交付模型如圖3 所示.

Fig.3 The agile way to deliver a product圖3 敏捷產品交付模型

系統軟件的研發是多個版本持續發布的過程.第1 個迭代開發,到版本正式交付是版本的開發周期.敏捷軟件開發中,每個迭代的交付中既包含了軟件特性的潛在可交付,也包含了文檔的潛在可交付,經過軟件和文檔的系統測試環節之后,就進入正式交付狀態.基于該模型,文檔的開發不再是一個單獨的流程,而是與軟件同步的迭代開發、持續交付的流程.

文檔DevOps 是基于DevOps 理念的解決方案,通過文檔開發的方法、流程和配套的支撐工具平臺,實現大型軟件系統各類文檔的自動化構建與持續發布.在解決方案中,流動的基本對象是信息單元,它們按照組合形式和依賴關系的不同而有不同表現,共同構成文檔DevOps 的3 層模型.

如圖4 所示,領域模型提供了文檔DevOps 的基礎信息單元定義.通過文檔架構的規劃以及可以重用的同源信息單元的梳理,設計出各領域的不同類型的信息內容的模板,例如需求、方案、場景等,每個模型的模版中都包含大量的信息單元,如需求模型中包含“需求編號與標題”“背景”“預期收益”“驗證準則”“相關波及”等.我們有一套名為“文檔架構工作坊”的活動,用來完成文檔架構規劃和同源信息單元的梳理,其中通過規劃、研發、工程等角色的協作分析,產生領域模型的定義與書寫模板.研發過程中,各個角色再分別負責軟件系統工作中與自己相關部分信息單元內容的輸出,大量的信息單元可以有機地組合成為軟件系統的文檔.領域模型可以實現專業的人輸出專業的信息內容,如高層設計HLD(high level design)、特性描述FD(feature description)、特性指導FG(feature guide),保證了文檔的準確性和完整性.而基于同源理念規劃設計的信息單元,也給文檔內容一致性提供了保障.

Fig.4 The model of document DevOps圖4 文檔DevOps 模型

信息流定義了各類軟件研發流程活動中需要輸出的信息單元,并配置了這些信息單元如何組合成最終交付文檔內容的映射關系,即信息單元的關聯關系.具體而言,就是根據“文檔架構工作坊”活動輸出的軟件系統文檔架構,結合信息流中的信息單元及單元之間的引用、鏈接等關系,設計出文檔的組合裝配流水線(含應用在DevOps 工具鏈的各類配置文件),就可以實現不同類型的文檔的自動化構建、檢查、組裝、發布全過程.軟件與文檔融合的信息流的流程也保證了軟件與文檔的一致性,為文檔發布的及時性提供了保障.

應用層根據文檔面向的用戶不同,可以提供不同的樣式疊加,即在DevOps 工具鏈編譯完成內容準備后,再利用如HTML 的CSS 等技術,調整樣式交付文檔的表達格式.疊加樣式前的內容,是由上一步的信息流輸出的.整個樣式疊加過程也是在DevOps 工具鏈中完成,通過配置文件可以進行針對用戶的需要進行內容的動態篩選和定制化輸出.

根據以上分析,文檔DevOps 方案與業界常見的兩種方案的對比見表1.

Table 1 The comparison of solutions表1 解決方案比較

其中,文檔DevOps 的收益來源于領域模型和信息流帶來的同源效果,可同時為文檔開發帶來兩種復用.

(1)交付文檔間的內容復用;

(2)過程文檔和交付文檔的內容復用.

DITA 方案在第1 點上是通過Topic 在交付文件間復用;開源方案主要考慮第2 點的優化,聚焦利用研發過程內容來輸出最后的交付文檔.本文的文檔DevOps 方案利用同源設計打通了交付文檔間和過程文檔間的內容引用關系,并將其自動化,同時獲得了這兩個方向上的收益.

我們在60 多個電信軟件項目中應用了文檔DevOps:軟件版本和產品文檔之間的滯后時間平均從30 天左右縮短到不到2 天,文檔的一致性準確性問題也大幅下降,下降幅度達到70%以上.

如圖5 所示,軟件版本和產品文檔發布節奏對齊后,文檔DevOps 擴展了傳統DevOps 的應用領域并支持連續的文檔發布,實現了DevOps 的全價值交付.

Fig.5 Different delivery paces of software and documents圖5 軟件版本和產品文檔發布節奏對齊

2.2 業務流程

從文檔交付業務流程來分析,文檔DevOps 有4 個環節:生產、構建、發布和反饋,具體如圖6 所示.

Fig.6 The process of document DevOps圖6 文檔DevOps 的業務流程

2.2.1 生產環節

生產環節是文檔的信息內容的產生過程,需要利用到分布式協同內容編寫的工具,如wiki 等,并在開發流程中內置好文檔任務指派和自動化編譯檢查的功能.例如,在下發需求分析任務時,同步下發一個產品的特性指導手冊的更新任務,將分析好的需求相關內容體現到產品特性指導手冊中.生產環節有如下特性.

(1)流程融合:生產活動貫穿于整個軟件交付流程并與之融合,信息單元的輸入、輸出、承擔的角色都依托于軟件交付流程的輸入輸出及軟件交付的角色,保證了文檔與軟件的節奏同步.

(2)全員協同:軟件系統的各個角色共同承擔文檔內容最終交付的職責,規劃、研發、工服、技術寫作者、翻譯等輸出的內容均要求達到可以對外交付的標準.信息單元由最熟悉內容的角色輸出,準確性和專業性得到充分保障.例如,研發人員最熟悉他們開發的軟件功能,直接由他們輸出功能信息,可以有效避免知識轉移過程中的失真.技術寫作人員熟悉文檔讀者的閱讀習慣和使用場景,可以站在用戶角度測試最終文檔,提升可讀性、可用性和規范性.

(3)組件化標準化:為了滿足軟件開發活動和外部文檔的交付需要,同時最大化地降低冗余,需要對內容進行信息單元的可重用的組件化設計,采用模版進行標準化輸出.與代碼的模塊化或函數的設計,以便代碼可以更大范圍地加以重用,信息單元的設計可以大大減少冗余的內容編寫,降低文檔編寫的人力成本[25].信息單元既作為軟件的輸入,又是最終文檔的構成部分,因而較好地實現了軟件與文檔的一致性,也滿足了信息單元在多個文檔的同源和一致性.

2.2.2 構建環節

構建環節是文檔的信息內容的加工與文檔合成.這個環節是當感知到內容編寫工具中的信息單元內容變化并被提交保存后,根據存儲在文檔DevOps 工具鏈中的文檔架構配置文件(其中描述了信息單元和最終交付文檔間的映射關系),觸發自動流程,將以此信息單元為文檔素材的相關交付文檔重新進行組合和內容更新,并完成基本的文檔質量檢查.這個環節有如下特性.

(1)代碼化:基于代碼的理念和實踐,進行文檔內容的信息單元的管理.如文檔素材的信息單元用代碼的管理工具git 來管理;通過類似代碼編譯鏈接的工具,將不同格式和內容的信息單元加工、組合、打包為不同格式的文檔;通過類似靜態代碼檢查的工具,實現文檔內容的質量檢查.代碼化有助于把敏捷技術實踐引入到文檔開發中,支撐文檔的敏捷開發,給文檔與軟件的同步發布提供了基礎.

(2)自動化:DevOps 倡導自動化一切,為高效交付、質量內建奠定基礎.文檔DevOps 貫徹這一原則盡早、頻繁、持續地自動化所有和文檔開發相關的活動,包括采集、組合、打包等.

可視化:對文檔的信息單元輸出、自動化流程、質量、最終輸出物的可視化,有助于整個團隊了解文檔的當前狀態,充分暴露問題,促進成員團隊的相互合作.

2.2.3 發布環節

發布環節是文檔發布與獲取的環節.這一環節需要用到在線的發布瀏覽系統,內部讀者可以通過這個系統進行在線的評審與外發管理,外部讀者可以通過系統查看和下載文檔.此環節有如下特性.

(1)體系化:各類文檔以結構化方式來呈現和展示,用戶可以根據文檔體系快速瀏覽和查找到需要的內容.

(2)定制化:文檔傳遞的信息可以按照用戶需要的格式和針對性內容來獲取.大型系統軟件的完整文檔包體積達到1GB 以上,不便于快速傳遞和精準查閱.文檔DevOps 提供靈活的內容動態篩選和不同類型格式的定制導出.

(3)用戶體驗:用戶獲取的信息不僅僅是靜態的文檔,還有音視頻信息、模擬和互動式的指導信息.移動互聯網的普及,也引出移動終端的訪問等需求.文檔DevOps 提供多樣化的發布形式及多樣化的訪問獲取方式.

2.2.4 反饋環節

反饋環節是文檔的評價、故障和建議的反饋的環節.這一環節一般內建在線上發布與瀏覽系統中,內部讀者可以通過這個系統進行評審意見管理和問題跟蹤,外部讀者可以通過系統進行感受評價、問題反饋和提出建議.這些跟蹤項將進行閉環管理,往往由提出人負責驗收關閉.此環節有如下特性.

(1)快速反饋:作者在完成并提交信息單元后,產品文檔的構建和呈現在分鐘級完成,審核人員或文檔用戶可以對文檔進行在線瀏覽,并直接進行批注、評論、打分等質量反饋活動,快速反饋讓編寫人員、審核人員及用戶的溝通順暢、頻繁.

(2)快速閉環:用戶反饋的問題快速傳遞到作者后,可以快速得以修復,文檔修訂后的結果也能快速發布給用戶,形成閉環.快速閉環減少了錯誤最終出現的機會,文檔質量得以提升,文檔交付速度得到提升.

從上述各個環節的特點分析來看,文檔DevOps 方案較好地支持了敏捷研發模式下的大型軟件系統的文檔特性要求.

采用文檔DevOps 后,生產環節的全員協同和組件化+構建環節的自動化和可視化+反饋環節的快速閉環的特性,會對準確性提升有明顯貢獻,同樣地,表2 中還分析了文檔完整性、及時性和可用性所涉及到的各個環節的關鍵特性.

Table 2 The effort of all activities of the solution表2 解決方案各環節的貢獻表

2.3 系統架構

文檔DevOps 是涵蓋文檔全生命周期的工具集和完整的解決方案,整體架構如圖7 所示.

Fig.7 The architecture of document DevOps圖7 文檔DevOps 系統架構

文檔DevOps 都建立在軟件版本的DevOps 工具鏈和云設施平臺上,以確保和軟件開發流程與文檔開發流程的融合,便于軟件研發和內容編寫同步進行.

中間是文檔DevOps 平臺,通過構建的產品文檔的交付工具鏈和提供的服務,讓文檔編寫人員專注于內容創作.

建立在文檔DevOps 平臺之上的是面向產品文檔解決方案,由各類Pipeline 和具體配置構成,方便、快速地提供不同文檔的開發和發布環境.

文檔DevOps 的3 層模型間是有依賴關系的,上層的功能是下層工具鏈提供的.例如解決方案層的FG/FD文檔生成流水線,由中層的文檔DevOps 平臺的各種服務/工具組合而成;進一步地,中層平臺中的文檔CI 服務,能夠將代碼化后的文檔進行類似編譯轉換的過程,生成最終交付文檔,這一過程又依賴版本DevOps 工具鏈中的各類處理代碼的工具支撐.

文檔DevOps 平臺是文檔DevOps 整體解決方案的核心和主體,我們把對應的實現系統稱為iDoc,其主要包含4 個部分,如圖8 所示.

(1)領域模型庫

領域模型庫中包含了各領域的內容輸出模版,比如需求模版、方案模版等等.代碼、模型腳本或注釋中包含的信息也可以作為文檔素材來源,所以也是領域模型庫的一個部分.每個模版中包含了不同的章節,每個章節信息類似DITA 中的Topic,是相對獨立的標準化的信息單元,也定義了單元模版.iDOC 的模型庫提供標準化的模版,各產品可以直接引用標準化的模版,也可以結合項目自身特殊情況進行適當的優化或定制本項目模版.

信息單元是對交付文檔的信息架構進行分析,提煉相對獨立的信息元素,再結合軟件交付流程輸入的需要,整理各環節的信息內容的輸出,消除重復信息后,進行標準化設計后形成的.每個信息單元都有明確的角色和責任人,承接該單元內容輸出.

(2)內容生產工具

在敏捷的研發模式下,文檔也是由全功能團隊協同完成交付,不同崗位的角色在工具選擇上往往存在差異,為減少項目在寫作習慣上的切換成本,iDOC 具備靈活支持多種不同生產工具編寫的能力.比如WIKI,提供了良好的多人在線協同編寫的功能,有很多企業用于內外部文檔協作[26];Word 是最為常見的文檔編寫工具,規劃或工服崗位已經習慣并且經常有離線編寫場景;MarkDown、ReStructureText 是開源相關的項目研發人員保持與社區同步的文檔編寫方式;XML 是技術寫作者最熟悉和專業的協作方式.

Fig.8 The platform framwork of document DevOps圖8 文檔DevOps 平臺架構

通過對多樣化工具的支撐,產品的各類崗位都可以用最熟悉的方式輸出信息單元和領域模版的內容.

(3)構建發布系統

構建發布系統是iDOC 的核心部分,在引用了DevOps 的自動化工具,如Jekins、Gerrit、制品庫的基礎上,開發了采集器、掃描器、內容管理系統、編排器、發布引擎5 個大子系統.

·采集器:根據項目的配置信息,負責對多種格式的信息單元的來源進行自動化的采集、轉換以及內容的標準化.

·掃描器:根據通用檢查規則及項目的自定義規則,負責對信息單元內容的自動化掃描檢測,及時反饋內容編寫的錯誤,如用詞規范、單詞拼寫、模版規范性等問題.

·內容管理系統(content mangament system,簡稱CMS):CMS 對項目的所有內容素材進行代碼化的管理,可以基于內容進行版本分支管理,實現文檔信息的歷史版本回溯與修訂.

·編排器:根據發布文檔類型,編排器按照不同的編排規則進行信息單元的自動化的組合拼裝.項目可以直接引用iDOC 的通用編排規則,也可以通過配置腳本進行編排方式的調整.

·發布引擎:根據編排器生成的內容信息,發布引擎生成各種類型的外發格式的文檔,如自定義文檔包、PDF、WORD、CHM 等等.同時還可以根據用戶需要,動態定制內容,生成個性化的文檔包.

(4)內容呈現與反饋

文檔發布之后,iDOC 提供多樣化的文檔瀏覽獲取方式,如在線的技術支持網站、離線閱讀器、移動終端訪問閱讀等.同時,在各種瀏覽方式下,提供快速發批注、評論、打分等功能,并將相關信息傳遞給作者,作者可以進一步交互互動,對文檔進行修訂,形成快速反饋和閉環.

3 文檔DevOps 方案實現

為了能夠有效地解決大型系統產品文檔交付的“四性”:準確性、完整性、及時性和可用性,文檔DevOps 必須具備以下屬性.

(1)系統軟件的產品文檔都是由多人協同才能完成的,同時,文檔與文檔之間的包含引用關系也非常復雜,為了減少人為的拋接和內容的重復編寫,降低文檔的維護成本,提高文檔的準確性和完整性,要求文檔DevOps能夠支持復雜文檔信息架構和引用關系可配置,同時支持內容做到一次編寫,多次引用,做到同源維護.

(2)系統軟件一般由多種組件組合集成發布,比如開源組件、自研組件等,產品文檔也是由相關組件的文檔進行集成而發布的.而每種組件的文檔開發方式可能存在不一致,比如開源采用MarkDown 方式,自研組件可能采用Wiki 或DITA 的方式進行開發,但是文檔最后發布需要統一文檔包發布,這就要求文檔DevOps 必須要能支持多種開發格式,最后統一格式打包發布,因此,文檔DevOps 需要有多種格式轉換的統一標準和平臺,以便支持文檔信息架構和引用關系的編排.

(3)讓文檔寫作者在研發過程中只關注于文檔內容的編寫,其他交付過程全部自動化,從而提高交付效率,做到文檔和版本同步發布,解決文檔交付的及時性.因此,要求文檔DevOps 的CI 效率必須對齊軟件DevOps.基本前提就是要實現文檔代碼化管理,基于代碼管理的易分析、可自動檢查、可構建等特性實現CI 效率提效.

3.1 內容同源可靈活配置

實現內容同源可靈活配置,需要具備如下3 個關鍵要素,其中,前兩個要素是內容同源的基礎,是第3 個要素的前提.

(1)文檔架構設計,根據文檔的用戶需求,優化交付文檔的結構.

結構化的文檔是內容同源的基礎.項目針對用戶的工作場景和工作任務進行分析調研,結合用戶需求,由文檔架構師對現有文檔體系、各類文檔的章節進行優化,確保每篇文檔內容是用戶所需要的,每篇文檔內容完整,其中每個章節的內容相對獨立和完整.

(2)信息單元梳理,信息單元的承接人員、流程活動、輸出樣板.

外部文檔的架構確定之后,需要梳理文檔相關的信息單元.

·根據外部文檔分析梳理信息單元.根據外部文檔的重要性排序,由文檔架構師與項目的系統工程師、業務分析師BA(business analysist)研討,逐一分析文檔中各章節的內容,將章節內容拆分為各領域的信息單元,類似DITA 中的Topic.信息單元不能過小,需要具備信息描述的完備性,但也不宜過粗,以免影響信息單元的可重用性.例如,特性指導書,應該包含特性描述、特性背景、特性實現原理、特性配置等等內容.分析過程中,需要記錄文檔章節與信息單元的關系,如拼裝、鏈接、引用等,記錄信息單元內容要求.

·根據軟件交付分析梳理信息單元.根據軟件活動的輸入和輸出,由EPG 與領域專家分析整個產品的交付流程中每個環節和活動應該輸出的信息單元.例如,開發實現活動中,需要有特性的實現原理、特性的交互、特性的關鍵技術等信息單元.分析過程中,需要記錄流程活動與信息單元的關系.

·整個文檔交付體系、軟件交付流程梳理完成之后,對分解出大量的信息單元進行領域的歸類,對各領域的信息單元進行審核,內容有重復交叉的信息單元,要消除重復或進行信息單元的拆分;對于信息單元包含內容過多的要拆分,顆粒度以單個角色在單個領域活動中可獨立完成為適宜.信息單元優化和調整后,要同步修訂文檔與變更之后的信息單元之間的關系.最終可以在各個領域得到軟件的完整信息單元,例如用戶需求領域的信息單元、特性領域的信息單元...各領域的信息單元可以共同來支撐整個文檔體系的交付與軟件的交付.

由圖9 所示的示意圖可以看到,外部交付和產品交付的內容與過程內容之間存在著同源關系.

Fig.9 The diagram of content single sourcing圖9 內容同源示意圖

·與各領域的代表商定承擔信息單元編寫的領域責任人及編寫要求.根據領域的信息單元之間的關聯關系,可以確定領域的模型模版,如用戶需求說明書模版、特性說明書模版,其中每個章節都屬于某個信息單元,有對應的責任人和編寫樣例.

圖10 所示為經過信息單元分解之后,各流程活動中對應角色需要輸出的需求領域的信息單元,這些信息單元組成了需求說明書、特性說明書的模版,最終,其中部分信息單元會抽取到交付文檔特性指導書中.

Fig.10 The association of R&D process and document content圖 10 研發過程和文檔內容關聯示意圖

(3)靈活配置管理,利用編排器組裝生成最終文檔.

上一步驟中記錄的文檔與信息單元之間的關聯關系,可以提取出交付文檔與信息單元之間的配置關系,形成文檔Devops 編排器的配置文件.編排器結合配置文件,可以實現各類信息單元的自動化組合拼裝.配置文件納入內容管理系統中,基線化管理,一旦配置好之后,可以持續運行,并且可以隨著文檔架構的優化,動態調整配置信息.

3.2 多格式轉換的標準和平臺

如系統架構的生產工具所示,文檔DevOps 需要面對多樣化的編輯工具和多種內容格式的信息單元,最終的文檔可能是來自不同格式的組合拼裝而成的,需要解決如下問題.

(1)采集信息單元的標準化

采集器的主要功能是原始信息單元的采集,另外還有一個重要的功能就是信息單元標準化.即將多種格式統一轉換到HTML,并且對信息單元進行識別和標準化,這個過程給后續的內容檢查、編排、發布等環節提供了統一格式的信息單元,降低了整個系統的處理復雜度.如果有項目在生產工具上有遷移,只需調整采集器的配置即可;有新格式的工具引入,也只需要增加采集器對新格式的適配,項目即可完整使用iDOC 系統的原有的一系列功能,如內容檢查、編排、多種文檔發布等等.

(2)統一的內容管理系統

MarkDown、ReStructureText、XML、HTML 等格式與代碼接近,適合于用SVN 或Git 來管理,但Wiki 是自己有一套數據庫來管理內容,因此給內容的統一管理形成了障礙.而且,Wiki 的內容管理是基于單頁面的,每個頁面都有相對獨立的版本號來管理,無法進行多頁面內容的統一版本管理,無法滿足產品的批量文檔內容的版本管理需求.

iDOC 的CMS 具備管理Wiki 的在線系統內容的能力.通過Jekins 系統調度周期性的檢測工具,檢測Wiki空間中各個頁面的更新情況,一旦有內容修改,觸發采集器對內容進行提取,保存在Git 中,確保內容的完整性和版本管理的一致性.

并且,iDOC 在Git 的分支管理基礎上增加Wiki 的分支內容的檢出功能,可以根據需要將Git 中歷史分支內容檢出到Wiki,內容修訂完成后可以采集修訂后的內容到Git 中,實現對歷史版本的文檔內容的變更.

3.3 文檔CI的效率

文檔DevOps 要讓文檔編寫人員只要專注于內容編寫,就需要解決如下幾個問題.

即見即所得:文檔開發人員在編輯環境編寫的內容要能在發布環境快速看到最終結果,便于快速反饋文檔編寫質量.因此要求從文檔開發到文檔發布的流水線效率必須在分鐘級的效率范圍內.

文檔質量內建:文檔格式、文字規范性、內容正確性和規范性要求等有明確規則和規范要求的都需要在流水線中自動檢查,及時反饋并修訂,避免低級或規范性的錯誤,提高文檔質量.

解決以上兩個問題的核心要素就是文檔代碼化管理.為了支持代碼化管理,需要支持標記性語言存儲,標記性語言便于分析,比對分析和自動化檢查,同時可支持靈活組合和打包,因此,文檔DevOps 可支持HTML、XML、RST 等格式的存儲和管理.

代碼化編寫文檔后,需要將文檔從編寫格式轉換成發布格式的過程,我們稱其為發布過程.例如:通過DITA進行XML 源文件到HTML/PDF 等格式在編譯轉換過程.

發布過程是一個高頻和大范圍使用的功能,編譯提速的意義非常大.使用iDoc 能將單次發布速度由原來的3 小時縮短到2～5 分鐘(如圖11 所示),原本發布周期也由原來的幾天一次,變為現在可以隨時獲取到整合好的發布版本.全流程周期縮短了96%,人工工作占用大為降低.

Fig.11 The CI of document圖11 文檔CI

3.4 方案實施實例

舉例說明:圖10 中FG 文檔的內容素材主要來自于兩篇過程文檔《用戶需求說明書》和《特性說明書》.

(1)在生產環節中,通過“FG 文檔架構工作坊”的活動,完成FG 文檔架構規劃和同源信息單元的梳理,明確《用戶需求說明書》和《特性說明書》各個信息單元的開發能夠滿足FG 文檔的交付.接下來,對各個信息單元的開發活動進行跟蹤管理,描述如下.

·背景知識、客戶收益、系統架構,來源于需求活動之用戶需求環節,我們的市場專家輸出;

·特性分析、關鍵技術、業務流程等,由BA 在產品需求環節,進一步補充;

·特性配置、測試用例等,由QA 在測試驗證環節,完善素材;

·其余的參數、計數器、告警等,散落在研發的各個環節中進行輸出.

(2)在構建環節,利用“FG 文檔架構工作坊”的梳理結果,生成配置文件表達FG 文檔的架構設計,將素材的關系、邏輯結構進行準確定義.當生產環節的信息單元被修改后,文檔DevOps 工具鏈自動地將各個信息單元部分連接成最終交付文檔,其中一個配置文件如圖12 所示.

Fig.12 The configure file圖12 某配置文件

工具鏈根據配置文件完成內容編排、內容生成、內容格式化、內容檢查、內容打包輸出等過程后,編譯出文檔后就進入到下一個環節.

(3)在發布環節,文檔DevOps 平臺自動地將內容部署到內部在線系統上進行閱讀評審,結束后根據版本發布決策,階段性部署到公司的制品庫上,供工服、客戶進行下載使用,也可以部署到e 讀服務器進行離線閱讀.

(4)反饋環節,會包含在我們內外部的在線系統中,包括兩個部分.

(a)針對研發過程的內部反饋,包括內容檢查結果、批注建議,形成FG 閱讀質量和體驗的度量數據,便于持續改進;

(b)針對交付之后的外部反饋,包括客戶滿意度、客戶意見等,利用故障跟蹤管理系統,對FG 文檔進一步改進提升和問題閉環.

4 實施效果

從ZTE 開始推廣實施敏捷開始,一部分研發項目就意識到敏捷研發模式下的文檔交付的問題,開始有項目探索文檔的敏捷交付實踐,進行文檔持續集成的嘗試和文檔自動化檢查工具的應用;內容建設上,由文檔架構師、項目技術骨干、技術教練合作,進行同源的規劃設計,試點項目的效率和質量上有明顯提升;2017 年正式提出文檔DevOps 的概念,并將其作為基礎設施數字化建設的3 條主線之一,開始加快平臺iDoc 的建設和在公司內推廣使用.

截至2018 年6 月,文檔DevOps 平臺已支持60 多個項目.實施項目以產品研發項目為主,產品類型覆蓋有線系統產品、無線系統產品及終端產品.研發項目的規模,從20 左右到1 000 人以上的項目都有,其中一半左右的項目規模在50～300 人之間.

已有結果度量數據的約23 個項目中,為觀察典型項目的收益,我們選取了有代表性的9 個項目作為分析樣本,其規模和產出文檔數見表3.

Table 3 The typical projects表3 選取的典型項目

偏大和偏小的項目,在文檔DevOps 實施后的優化效果上,也有不同程度的體現.但本文研究對象主要考慮系統產品類的典型項目,目的是確保我們的改進對這些項目是有效的,對其他類型項目的有效性缺乏更多數據,并不是本文重點.

項目基于文檔DevOps 平臺的交付文檔類型,包括售前規劃主導交付的特性說明、售后主導交付的版本發布說明書、研發主導交付的特性指導書、在線幫助、參數手冊等文檔,現階段收益比較明顯的是特性指導書、版本發布說明書和在線幫助.

從實施后的度量數據看,在4 個方面有明顯的改進效果.

(1)周期縮短,成本降低

表4 是某類系統產品項目中新編寫單篇特性指導書的效果數據.平均投入時長整體的時間周期縮短了30%以上,人力投入減少44%以上.

Table 4 The effort of feature guides delivery表4 特性指導書交付效果

特性指導書原來是拋接方式:研發人員寫完過程中的需求特性文檔,再編寫交付文檔素材,技術寫作者再重新寫交付文檔;文檔DevOps 實施后,3 個類型的文檔通過信息單元精簡合一,研發人員與技術寫作者在過程中協同編寫的信息單元,重復內容的編寫消除了,文檔的周期縮短,投入也有所降低.

表5 是某類系統產品項目中單篇版本發布說明書的效果數據.一個中等規模的發布版本所涉及的需求條目、故障條目分別在30 條左右,其人力投入由原來4 人天左右減少到1 人天,投入大幅縮減75%以上,文檔準確性得到提升.

Table 5 The effort of release notes delivery表5 版本發布說明書交付效果

版本發布說明書原來純人工收集各類版本相關的需求、故障信息,再匯總整理成文檔,耗時耗力,也容易出錯;實施文檔DevOps,可以自動化地采集各需求管理、故障管理系統的信息.

在線幫助內容原來由研發人員編寫,與技術寫作者的其他用戶文檔有很大部分內容存在重復.某類系統產品項目實施文檔DevOps 之后,研發人員與技術寫作者協同編寫一份內容,同步生成幫助內容和用戶手冊兩類文檔,降低人力成本40%左右.

(2)及時性提高

文檔DevOps 有流程融合的特點,在軟件交付的過程中,文檔的信息單元同步輸出,文檔內容在軟件交付過程中迭代生成和補充完善,文檔與軟件同步交付.

根據某類系統產品項目實施文檔DevOps 一年多來的文檔發布及時性統計數據,特性指導書等交付文檔滯后版本時長從實施之前的平均2 個月以上,縮短到平均2 天左右.

(3)質量顯著提高

通過文檔DevOps 的實施,確保文檔的信息單元是研發流程中某些重要環節的輸入或輸出,如特性說明書是軟件特性實現的輸入,參數說明是軟件的領域模型的輸出.信息單元與軟件開發之間的密切關系,促進了文檔與軟件之間的一致性、準確性、完整性明顯增強.某類系統產品項目對特性指導書、參數手冊等文檔近1 年的故障數據統計分析,上述3 類問題下降70%以上.

DevOps 的基本理念是嵌入質量保證手段,特別是使用實時的用戶監控發現問題[27].文檔DevOps 遵循這個理念,提供了CI 自動化快速反饋,提供實時的瀏覽和批注等功能,質量改進效果也比較明顯.原本需要人工檢查的問題,應用了自動化檢查工具后,針對中文、英文的文檔提交過程中盡早地發現問題.某類系統產品項目版本發布閉環的故障均超過千次以上,文檔質量問題的閉環平均周期縮短60%以上.

(4)可用性有待數據驗證

對于文檔的可用性,當前內部用戶反饋效果較好,暫時沒有量化結果,還有待進一步收集內外部數據.

5 討 論

5.1 改善的原因分析

取得文檔過程的改善,我們認為主要的原因有:

(1)做到文檔開發過程和軟件敏捷開發過程融合,使得文檔的內容由最熟悉的人在開發過程中同步輸出.研究表明,DevOps 高效流程可以提效超過20%以上[28],原來的模式中,兩個過程是分離且串行的,導致大量的信息傳遞;現在文檔DevOps 的做法提升了文檔的及時性、準確性和可用性.

(2)通過信息流梳理,對研發過程需要輸出的信息單元進行了分析和解耦,利于第1 條的同時,確保完整涵蓋最后產品文檔的交付要求.原來的模式中,缺乏一個明確的過程內容和交付文檔間的對應關系管理.現在的做法提升了文檔的完整性、準確性和可用性.

(3)在內容的編寫過程中,通過文檔CI 實時地給予質量反饋.這樣的反饋,是面向最終要交付的產品文檔,即讓所有人在輸出內容時都遵循交付的標準.原來的文檔內容的反饋周期長,反饋時間點滯后.現在的做法提升了文檔的及時性和準確性.

本文解決的問題,在業界也有一定的典型性,可以為DevOps 實施企業提供參考.

5.2 適用性與限制

使用文檔DevOps 的方式,對研發過程中的工程師,提出了文檔寫作上的要求.

(1)站在用戶的角度編寫內容

研發工程師描述內容時,很容易站在實現者的立場,而不是用戶的角度,這個需要意識上的持續轉變.

(2)需要更加細致的描述

研發人員常常討論完內容后,并不詳細描述相關的文檔,而是直接開始編寫代碼和用例,這會導致本來已經顯性化的知識重新變為隱形,對知識傳播非常不利.使用了文檔DevOps 后,會有利于改變這種情況,但需要研發人員對討論的結果進行細致的整理和文字描述.

(3)樣式標簽與內容解耦和標準化

大量的信息不再通過拋接給技術寫作者來編寫,而是由研發人員在開發過程中整理好,這就需要支撐的系統能夠很好地將樣式標簽與內容解耦和標準化,并對一些工具限制對研發人員進行培訓.

文檔DevOps 的流程與架構適用已經有敏捷和DevOps 基礎的團隊,對于軟件版本的DevOps 的運作成熟度,會直接影響到文檔DevOps 的執行效果,原因是文檔DevOps 的很多流程是內嵌到軟件版本的研發流程中的.

另一個限制性來自于文檔DevOps 面對的產品文檔的變化程度.實施文檔DevOps 的過程,將涉及到大量內外部文檔內容與格式的分析與定義,需要的相關干系人共同參與演進過程,這會消耗大量的人力物力,對于已經成熟的產品,其產品文檔變化已經不會很大,完整實施文檔DevOps 的性價比低,不適用去改造.

5.3 文檔價值交付的文化轉變

區別于傳統文檔交付,在文檔DevOps 的交付方式中,文檔內容編寫由技術寫作者主導轉移到研發人員同步編寫.對于研發人員而言,看似額外多出一項非開發任務,而且疑似和敏捷價值觀中的“可用的軟件勝于面面俱到的文檔”有所沖突,轉型初期可能會出現研發人員抵觸文檔寫作的現象.

實際上,敏捷價值觀中簡化文檔的本質是指要消除不必要的文檔,而本文中的文檔DevOps 中涉及到的文檔都是需要對外交付的必要文檔,是產品價值的重要部分,因此不但沒有沖突,而且如第3.1 節中的同源引用的方法有助于團隊判斷文檔的必要性,從而可以消除多余的文檔.

另外,為了確保研發人員有意愿和有能力承接文檔開發工作,對組織文化也要有如下轉變.

(1)引導職責共享文化:敏捷倡導全功能團隊,聚焦價值交付.而文檔作為產品價值交付范圍之一,團隊也需為文檔交付負責.文檔DevOps 中的協同開發可以支持團隊共同完成軟件和文檔的同步交付,做到職責共享.

(2)建立價值交付導向的業績評價標準:傳統研發模式中評價研發人員業績僅僅關注開發階段的工作業績,而忽略整體價值交付評價.在敏捷中強化端到端的價值交付理念,評價個人業績也轉向其在價值交付中的貢獻.這樣使得團隊和個人愿意認領文檔開發的任務.

(3)打造專注和極致的研發環境:文檔DevOps 通過簡化文檔開發復雜度,讓研發人員專注于內容開發.其中,文檔代碼化管理方式使得研發人員的工作方式類同于軟件開發,通過編排和模板屏蔽了文檔格式要求,降低了文檔開發的技術門檻,研發人員只要專注于他熟悉的內容表達,可一次性高質量完成文檔交付.

5.4 固有缺陷說明

文檔DevOps 的關鍵點是關于文檔內容的同源配置,這是它發揮價值的重要環節,也是其難點和固有缺陷的來源.

(1)同源配置來自于對文檔應用領域的準確理解和劃分,但這個過程是一個漸進的過程,所以會要求配置環節比較靈活,對穩定性和控制復雜度要求都很高.

(2)不同用戶對相同領域知識的定義,可能產生沖突,特別是在商業模式創新的領域,這將導致內容同源部分還是會必然引入重復或冗余,無法完全消除.但這個過程的分寸如何拿捏將會非常考驗信息架構師的能力.

5.5 對研發人員開發效率的影響

敏捷文檔交付的一個重要轉變就是讓開發人員直接參與最終交付文檔的創作,這看似會占用開發人員的本職開發工作時間,但也有可能會影響到原有的開發效率.

事實上,開發人員在傳統的開發過程中,為了確保開發質量,通常會編寫過程文檔,比如方案設計、詳細設計等文檔用于評審,這一般會占用開發10%～20%的時間.而且為了配合文檔創作者交付文檔,開發人員還需要為文檔創作者提供額外的素材文檔,這個也需要占用開發時間.敏捷文檔交付之后,開發人員在開發過程中就按照對外文檔的要求輸出文檔內容,該文檔可用于內部過程質量評審,同時還滿足對外交付要求.相對于開發人員的時間而言,還節省了對外文檔素材整理和交流的時間,所以,從開發人員投入總體開發時間來看,不會有太大的影響.

據某系統產品的單個需求開發人力成本統計,敏捷轉型初期需求人力開發成本呈下降趨勢,敏捷轉型之后需求人力成本基本保持穩定,說明文檔DevOps 方式的應用并沒有影響到開發本身的效率.如圖13 所示.

Fig.13 The labor cost per requirement of a project圖13 某項目每需求人力成本統計

5.6 未來工作

5.6.1 社區化

文檔更易于被用戶分享和傳播,帶來更多閱讀;滿足用戶更多的需求,用戶更便于表達建設性的反饋;文檔成為社區化交流的媒介.

每一個階段的社區化可以為文檔編寫發揮的作用,如圖14 所示。

Fig.14 The revenue of community-based approach of document DevOps圖14 文檔DevOps 社區化方式收益分析

5.6.2 云 化

云計算支撐了文檔生產、獲取、消費過程全部云化.文檔云化托管,從云端按需存取.

整個研發模式,需要建立在云技術基礎上,這樣才能真正發揮文檔DevOps 的快速協作的威力,滿足跨產品的同源要求.

5.6.3 智能化

人工智能作用在人、知識、產品這3 個領域間快速建立鏈接的行為上,是大勢所趨.首先在文檔內容生產、消費中,AI 已經嶄露頭角.

(1)給出同步翻譯的輔助指導

大規模軟件系統往往是國際化產品,研發人員一般只會使用母語寫作其中的內容,其他語言版本都需要專業人員翻譯,如果能夠在翻譯的同時,給出高質量的機器翻譯作為輔助參考,那么會極大地提升專業翻譯的效率.文檔DevOps 中能夠集成同步翻譯的輔助指導,是一個重要的改進.

(2)人工智能進行可讀性輔助判斷

可讀性是一個模糊領域的問題,可以通過分析技術寫作者持續地修改記錄,利用人工智能技術幫助提示出一些可讀性改進的建議,甚至將來80%的可讀性問題主要由工具來指出和完善.

6 總結

專業咨詢機構的調查顯示,DevOps 將會在系統軟件研發中得以大規模應用.本文重點討論的內容有:完善DevOps 在文檔領域的交付模式,探索其系統架構,并解決其中的關鍵問題.本文把這些工作統稱為文檔DevOps.

文檔DevOps 主要解決面向系統軟件的軟件版本和產品文檔同步交付的挑戰.在敏捷和DevOps 變革后,軟件版本發布節奏變得更加頻繁,而與之配套的文檔交付模式沒有發生對應變化時,導致了系統軟件的敏捷價值交付無法實現.

本文提供了文檔開發相關的流程與架構實現,通過如下3 個方面的工作來讓軟件版本和產品文檔同步發布,并且利用DevOps 的快速反饋優勢提升了文檔開發協作效率和產品文檔的質量.

(1)對信息流上的內容進行架構解耦,再利用工具/平臺進行同源引用,組合生成需要的各類文檔,增加了過程文檔與交付文檔、交付文檔之間的內容復用,提升了文檔準確性,同時,分析和改進產品文檔的完整性.

(2)構造文檔的CI 流水線,并在流水線中內嵌自動化質量檢查工具,做到快速反饋和質量內建,守護產品文檔的準確性和完整性.

(3)將文檔的開發過程與軟件版本的DevOps 融合,在統一的版本研發流程中,進行文檔的版本管理,確保產品文檔與軟件版本的同步開發交付,并打通用戶的反饋.

文檔DevOps 在幾十個項目中已被實際應用,也獲得了初步的推廣效果.進一步地,本文工作的意義還在于擴充了DevOps 的適用范圍,涵蓋了版本和文檔兩類對象.對采用敏捷開發模式的項目,文檔DevOps 的補充也完整地支持了項目的全部主要工作流程,為系統產品的價值交付奠定了基礎.