Ruddy Lee 分享空間

Emergent Design 演化設計

Agile Documentation 敏捷開發需要哪些文件?

with 2 comments

.

敏捷文件?  敏捷開發不是只要會動的原始碼就 OK了嗎! ?

.

客倌,不要開玩笑了! (關於敏捷開發不寫文件的傳說 — 那是神話!)

沒有文件的程式就像孤兒一樣,沒人認得出他來! 而沒有文件的專案,就像走私一批貨物一樣,少一樣或是多一樣也沒人知道。你會讓辛辛苦苦寫出來的程式像孤兒一樣沒人照料嗎?

再說;雖然原始碼是最佳的文件,但也是最不容易閱讀的文件。所以單單依靠程式碼來說明它自己是不夠的。單獨的程式碼是孤兒,沒有人知道它是做什麼的,更不知道該如何對待它。所以它需要一些足以代表它的說明。最好的說明當然就是文件囉!(簡報檔在此)

所以程式 >> 需要文件來替它作說明、更需要測試程式來保證它的好壞、也需要系統架構以便進行維護運作。

三種基本必備的文件:

  • 需求說明文件」: 作說明用

  • 系統概述文件」: 便利維護運作

  • 活文件」: 提供自動化測試的基礎

(請注意: 文件不是好的溝通工具,是不得已的時候才採用的溝通工具最好的溝通方式,是面對面站在白板前面的溝通方式,其次是通電話用聲音來溝通、用email,對溝通而言文件是單方面的、必需耗費較多時間又容易產生誤解的不良溝通方式)

communicationModes - 副本

文件不是好的溝通方式

在你開始動手寫文件之前,有幾件事必須先弄清楚:

 ※ 文件是寫給誰看的

很多人在寫文件的時候,忽略了自己準備開始寫的這份文件,是寫給誰看的? 他們可能是:

  • 客戶(對軟體專案而言,文件的第一大要求者是客戶。文件是客戶投資的回報之 一)
  • 自己(思考、規劃的草稿)
  • 團隊(成員相互溝通用)
  • 紀錄(手機拍照是絕佳的紀錄。經常有人是寫給老闆或主管看的,就當成是紀錄吧)

針對客戶你必須先弄清楚:

1. 誰是真正的客戶? 2. 他們需要的是什麼樣的文件? 3. 你要如何提供给他們? 4. 你要如何讓他們能夠很快的了解? 5. 你如何產出文件? 6. 你該放進去些什麼?

.

※ 文件是交接時的必備物件

程式設計師要學會如何把程式交接給自己。這跟學習物件化(OO)是一樣重要的事情,如果你找不到或甚至看不懂自己寫的程式,試問:要如何reuse呢? 又何必物件化?

最需要文件的人是客戶,再來就是程式設計師自己了。客戶是為了保障他的投資,我們則是重複使用(reuse)。千萬不要丟棄辛辛苦苦做好的物件化功能。所以一定要學會 Design for reuse.

re-use

Design for reuse 跟我們積極的作物件化(OO)是一樣重要的。 (參考自: http://www.cad.strath.ac.uk/~alex/aiedam96/ml-abstract.html)

.

版本控管文件程式

文件及程式是團隊共通的資產。對程式而言;極致編程XP首推,「集體程式碼共有」(Collective Code Ownership)的概念,讓團隊共同擁有程式,不但可以降低維護的困難,還可以讓大家看看那些厲害的傢伙是如何解決問題的。對文件而言;如同完美而簡潔的程式,令人心生佩服一般,乾淨而有序的文件,能夠贏得同僚之間的尊敬。(再說;沒有文件是很難看懂厲害的程式的)

 ※ 文件製作的價值觀: Good Enough 及四個準則

文件包含「概述部分」與「明確描述」的部分,二者都必需遵守文件的敏捷規範:

1. 一定要維持輕量化(lightweight)。 2. 產出文件一定要維持高品質,也就是具有:準確、最新的、高可讀性,足夠簡潔跟嚴謹的結構。 3. 撰寫文件,必需採用方便、易開發維護,並能夠產出高品質文件的工具。 4. 明確描述的文件部分,必須可以跟著程式碼做改變,也就是與程式同步。

usefulness - 副本

跟架構設計一樣 — 浮現式文件 Emergency Document

不能在專案一開始就把架構設計的工作做完,因為需求一直在變所以設計也必須跟著改變。這是敏捷開發較困難完備的一面。另外就是單元測試(Unit test)和測試開發(TDD),這二個被XP嚴格規範的程式員守則,隨時隨地做測試的高難度習慣,也很少人做得好。把他們引申到文件的開發上,你會發覺難度更高了,幾乎找不到程式設計師願意一邊寫程式一邊寫文件的,但這個動作便是所謂的「浮現式文件」 Emergency Document。寫文件的時機:

  • Before/ After
  • 撰寫程式文件的最佳時機,是在程式被認可為完成Done的時候,
  • 讓邏輯思緒做好最後的收斂動作 ,才是真正的Done。
  • (往往它可以幫你又找到許多邏輯思維上的缺陷!)

很少人會這麼做,他就好像要我們必須養成每天記帳的動作,大家都知道只有每天記帳才會知道錢都花哪裡去了? 可是你很難找到一個可以這麼做到的人。

 Just Enough 剛剛好就可以了

這是所有教敏捷開發的書本上都會提到文件製作的不二守則,然後就沒再說什麼了! 因此久而久之大家便把敏捷開發不做文件的神話當真了。其實是浮現式撰寫文件的嚴謹態度太難了! 而這些講敏捷的書是害怕強調文件製作會讓人們把注意力放錯地方了(該注意的是:正確的程式)。敏捷宣言第二條所說的「可用的軟體 重於 詳盡的文件」,就被拿來做為不寫文件的藉口。其實詳盡的文件雖然不如可用的軟體重要,但卻是一樣不可或缺的。

.

敏捷開發需要什麼文件呢?  light-but-sufficient

1. 提供 概述部分Big Picture 的文件。 「需求說明」文件: 能讓人很快弄清楚程式目的的文件。 「系統概述」文件: 能讓人很快弄清楚系統架構的文件。 (使用者故事對照 User Story Mapping 是最佳的文件之一)

scrum 課程

結構化的說明文件

2.  提供明確描述的活文件 Living document 。 解決「沒有銀子彈」的活文件。 活文件提供自動化測試的基礎。

「活文件」: 能夠伴隨著程式開發同步更新的文件謂之活文件。

given-when-then-1-638

以測試案例為文件

※ 邁向未來的文件

在你開始動手寫文件之前,請先思考部門或組織對文件的需求,運用未來的科技他應該會長成什麼樣子呢? 用未來觀去看待它,寫起文件來心情會好一些! 或許文件會像對程式的描述由像Word一般鬆散的文件製作 ,邁向結構化的多元結構,再走向模組化(Pattern)的樣式。

Document_new

結構化 Structured、模組化 Pattern

※ Big Picture 請參考 Agile Document (原書在此)

Written by ruddyllee

2015 年 01 月 16 日 於 09:11:42

2 回應

Subscribe to comments with RSS.

  1. […] 建構滿足使用者需求的軟體,最好的方法是從"使用者故事"開始。它即簡明扼要又清楚明確地描述對實際用戶有價值的功能。但它(使用者故事)不是規格文件,而是用來探討解答的抽象化方式,對於敏捷而言;真正的規格文件是誕生於持續的開發與維護當中。(敏捷文件;它跟程式的架構有著相同的產生方式,也就是衍生出來的,是一邊設計而同時又一邊撰寫出來的) […]

  2. […] 一些細節作法,請參考 : Agile Documentation 敏捷開發需要哪些文件? […]


發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / 變更 )

Twitter picture

You are commenting using your Twitter account. Log Out / 變更 )

Facebook照片

You are commenting using your Facebook account. Log Out / 變更 )

Google+ photo

You are commenting using your Google+ account. Log Out / 變更 )

連結到 %s

%d 位部落客按了讚: