敏捷開發中文件撰寫的必要性?

問題

這幾天在上敏捷開發與DevOps課程時,學員問到了一個非常有意思的問題。學員這麼說:

“Mike Cohn這類專家,對於User Story抱持一種用完可丟的想法(尤其是用紙本卡片時),但是團隊總會覺得有些討論過的需求沒有在 work item 之外的地方記錄時,只靠記憶力是很不可靠的。想請問老師對於紀錄專案諸項功能的需求文件,有沒有建議的作法?”

這個問題本質上,跟之前很多問到敏捷開發要不要寫文件,其實是有點類似的討論議題。

這個議題的緣由是因為,敏捷宣言中有這麼一條 “可用的軟體 重於 詳盡的文件” :
圖片

自此,開發人員分成了兩派。

一派人員認為這是指文件不需要繁瑣,但並非完全不寫文件的意思。(畢竟宣言中說的是 重於 )
另一派人員則認為,能用的軟體才是重點,程式碼本身應該就要有高可讀性,讓程式碼足以表達傳統的系統文件想要說明的事情即可,其他文件寫了以後也是會變,寫多了根本沒用。

和以前不同,最近這幾年上課時,我都不太想挑戰大家既有的想法。但既然同學問到了,我就說說我的看法。

真需要文件?

首先,僅用文件兩字,來表達軟體開發中所需要記錄下來的東西,其實是不精確的。即便再怎麼概括的分類,至少也能將軟體開發的相關文件分成兩大類。

一種是用來在開發行為發生前,描述需求的文件,這一類的文件主要是讓開發人員能夠清楚明白該怎麼開發用的;另一種則是在開發完成後,用來描述系統建立過程與現況的,這種文件主要是讓後續的維護人員(當然也包含開發團隊自己或後續接手加工的人),可以方便進行系統維護或功能添加用的。

圖片

當天學員所提到的 User Story,指的是前者。你會發現其實這一類的文件,不管是 User Story, Acceptance Critiria, 或是傳統的 Requirement Spec…在敏捷開發認為需求會持續不斷改變的這個前提下,這種文件的有效性其實極低,從寫下的那一刻起,就注定了它會淘汰和快速失效的命運。

因此,你會發現敏捷開發的思路上,對於 “寫” 這類文件,實在沒什麼興趣。所以寫這類文件時,往往是愈精簡愈好,User Story 就是這類的產物,它的主要目的也不是 “紀錄” 或 “存留”,而是 “引發溝通”

User Story 寫出來的東西也不是聖旨,就只是當下那一刻,我們 “對需求的理解”,透過

as [a type of user]
I want [some goal]
so that [some reason]

這樣的格式,引導(誘導)開發團隊與用戶之間能夠討論,所以這類文件,其實並沒有存留的必要,一個已經 done 的 User Story,不管是實體便利貼或是電子看板上的卡片,done就是done了,你以後再也不會去看它了。

所以我同意學員說的,User Story 存在著一種用完即丟的性質(不管是實體卡片或是電子看板)。

但這樣,所有討論的過程都沒有保存下來,後續怎麼維護系統呢?
因此,我覺得 “另一類的文件”,是有撰寫和保存的必要的。也就是系統維運用途的文件。

系統維運文件

這一類的文件,跟需求文件並不同。
撰寫的時間點也並非在軟體開發之前,而是在開發過程中或開發之後(因為需求持續改變,你愈早期寫愈沒有意義)。

這類文件是將來系統維護的依據,有一派敏捷人認為,透過程式碼本身可讀性的建立,可以降低對這類文件的倚賴,這是 Self-documenting code 的概念。

但這是不是表示,我們就完全不需要撰寫任何文件了? 我想不是。因為 code 再怎麼 Self-documenting,也很難100%取代 documenting。

但這個概念之所以吸引人,是因為大家不喜歡寫文件。

別裝傻,我認識的開發人員當中,程式碼寫得愈好的,就愈不喜歡寫文件。沒有例外。(至少我認識的人裡面,沒有例外)

因此,documenting是一個爛差事,但能不做嗎? 其實不能。
我同意,程式碼寫得愈漂亮,架構愈清晰,Self-documenting 就愈好,當Self-documenting愈好,對維運文件的依賴就可以愈低。

但現實總是殘酷的。
Self-documenting 能做得好的團隊,真的極少。而且這些團隊根本大部分本來就是身手高強的開發人員,才能把 Self-documenting 做的淋漓盡致、做的理所當然。然而,這一類的團隊,本身本來對 “維護文件” 的倚賴就極低。

從這個角度來看,維運用途的文件,是必要之惡,對於愈是 junior 的團隊就愈是重要,就像是你寫了一堆API,然後不寫個呼叫該API的文件給API的使用者,這有點不道德或不合理,是吧?

說到這邊,你可能會覺得,不對,其實現在寫API,可以透過工具自動產生呼叫文件啊? 沒錯。就是這個『自動』,我就在等你說到這個自動

自動產生文件

如果,我們剛提到的這一類系統維運用途的文件,可以透過工具自動產生呢? 就像是我們寫API後,用工具自動產生呼叫API所需的文件一般,那這樣的必要之惡,是不是就讓人覺得稍微沒那麼痛苦了些?

請看底下這段影片,特別是其中的 30 秒之處(我是建議你完整看完,但如果你等不及的話…),你會看到,我們開啟專案當中的幾個程式碼檔案,然後請 AI (GitHub Copilot) 閱讀這些程式碼檔案,並且幫我們寫出文件:

接著,我們把 AI 生出的文件,繼續讓 AI 加工潤飾,還可以改成表格(1分48秒),最後,把文件和程式碼一起,簽入版控,在 wiki 當中,就可以看到文件了(2分45秒)。

AI生成文件,再由開發人員進行 document review,最後更新到 repo當中,直接與 wiki 同步,過去的苦差事由 AI 代勞分工,這種作法豈不妙哉?

結論

敏捷時代,需求變更快速,保留需求討論階段的需求文件意義實屬不大,這類的文件即便寫了,到了專案後期可能也已經失效或失準,大概不太會有人有空去更新這類文件。它的用途比較屬於引發討論,而非陳述現況事實。這類文件寫不寫留不留看你,你的團隊人力很多,想把工時用在這裡我也不介意。

專案開發後期,針對系統後續的維護所需而建立的文件,我覺得是一種必要之惡,過去我們要撰寫或維護(更新)這類文件,必須花費大量時間,如今有了AI助手賦能,將這類文件寫得又快又好,過去一個下午的工作現在20分鐘就完成,這類苦差事似乎也不再讓人感到那麼痛苦了。

時代在改變著,很多傳統的思維碰到了新的科技,開始有了些火花被激盪出來,接下來還會怎麼發展? 很讓人期待。


參考 課程:
敏捷開發與Azure DevOps實戰

留言

這個網誌中的熱門文章

精彩(且驚人)的Semantic Kernel入門範例

使用LM Studio輕鬆在本地端以API呼叫大語言模型(LLM)

VS Code的字體大小

專業的價值...

使用AI(ChatGPT)對PR進行自動化 Code Reivew