敏捷開發中文件撰寫的必要性?
問題
這幾天在上敏捷開發與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實戰
留言