撰寫文件是件人人討厭, 但是沒有時又很痛苦的事. 那我們該怎樣處理呢?
首先, 在討論處理方法前, 可以思考這個現象: 他們不會看文件
TAGRI, They Ain't Gonna Read It.
這個現象是說, 在軟體開發過程中, 所建立的文件, 實際上很少人會去看. 因此, 需要思考怎樣寫文件才是合適的.
為甚麼人們會需要文件呢? 或者問說你在什麼狀況下會去看文件呢?
通常人們會回答:
當我要實作某個功能時我會看文件
和客戶吵架時要確認合約範圍時
要改別人寫的 code 時
….
你有沒有注意到, 這些事情上有個共同的特點, 大家都是遇到了問題, 想要”找答案”來解決. 因此
(1) 當人們沒遇到問題, 大多是不會看文件
(2) 那"找答案"這件事, 是不是只能靠文件, 相信是不見得. 如果有人跟你解釋後, 你應該就不會再去看文件.
因此 agile 想說的, 是想提醒你, 除了看文件外, 是否有別的更有效率的解法, 如果有就先用, 之後再來補文件. 如果沒人可以回答你的問題, 文件還是有幫助的.
那我們可以用什麼方式有效去解決找答案這件事呢:
(1) 溝通為先, 文件後補
可以先找到可以回答問題的人, 請他解釋如何處理你的問題, 讓你可以在花較短的時間, 就可以處理你的事情. 另一個人可以溝通完後再補文件. 尤其當他會被問很多次後, 他自己也會想把它寫下.
(2) 內部或是外部文件
有些文件只是團隊內部使用, 但是有些則是外面用戶在看. 如果只是團隊內部使用, 你就可以使用較簡單的格式, 或是比較方便的工具來撰寫. 例如使用 wiki, 以條列方式來描述. 但是外部文件, 通常需要遵守某些規定, 並且需要多次來回檢視, 所花的代價會比較大. 所以確認內部或外部會使用, 是一開始要注意的.
另外, 內部文件往往是在開發階段就會用, 例如 front end 和 backend 合作, 或者 RD 交給 QA. 這時候格式不是重點, 即時和正確是第一考量. 如果文件是開發完後要交給客戶, 往往可以最後再來補, 可閱讀性便是重要的考量.
(3) 確認誰是文件的用戶
首先, 要確認這個文件是會有人看的. 如果不是很確定將來誰會用, 那這份文件的優先順序往往不高.
不同用戶你要寫的內容會不相同. 例如某個功能會怎麼運作, 對於開發人員, 你可能會寫 class diagram 再加上 sequence diagram, 另一個 RD 就可以了解全貌. 但是對於測試人員, 你可能就要寫些運作案例, 或者會有哪些輸入參數, 以及會產生哪些結果.
(4) 和文件的用戶討論要寫什麼
寫文件和做產品一樣, 做出的功能沒人要是個浪費, 文件也是如此. 因此你需要跟文件的用戶交談, 了解哪些部份她想知道更多, 或者為甚麼他會需要, 以及如何使用你所寫的文件. 有時候你會發現用戶想太多, 這些他根本用不到, 或者有更簡單的方式來用.
通常, 一開始用戶知道的有限, 所以他要求要寫並且能用到的, 不見得很多. (這裡的用戶通常是團隊內成員). 隨著專案的進行, 了解的東西越來越深入, 這時候便會要求更多, 你才補上更深入的部份. 這樣你也不會一開始就寫一大堆.
(5) 單一存放地方
很多時候, 我們會把文件散落在各地, 就像 code smell 一樣, 容易會造成每個地方有不同版本; 或者是這個地方找不到, 就再生一個版本. 集中管理, 更新一個地方, 這樣才會省力並確保一致.
其實我就是不想寫, 找這麼多方法, 我也是不寫 (誤)
全站熱搜
留言列表
