iT邦幫忙

2019 iT 邦幫忙鐵人賽

DAY 22
0
Software Development

軟體開發隨筆談系列 第 22

淺論文件

昨天篇幅好像寫太多了,今天就沒什麼靈感了,大概都被昨天榨乾了,愣是看著電腦螢幕,過了十五分鐘還是沒想法,等等還要去《我或許沒那麼懂 Web》寫關於 Firestore 進階查詢的文章,得趕緊了。看了看昨天寫的文,就挑裡面其中一個議題來寫吧。

文件(Documentation)也是個常常展開爭論的議題。到底該不該寫文件、文件該寫多詳細、文件的定義是什麼、程式碼是不是就可以作為文件、註解算不算文件的一部分、為什麼同事都懶得寫文件、為什麼文件寫好了卻沒幾個同事想看、文件到底該怎麼寫⋯⋯等等,一籮筐的議題可以討論,為之召開一屆鐵人論劍都不為過。

先脫離上面各種各種的問題,回到寫文件的初衷,我想就是「讓別人暸解這個軟體」吧!那麼只要能達成這個目的的事物,應該都算是文件的一種型態,可能是註解、可能是程式碼本身、可能是簡單的 README 文件、可能是比較正式的軟工文件、也有可能是軟體使用者介面上的導引。我認為,只要能幫助我們暸解這個軟體,就可以是文件,包括幫助開發者暸解怎麼使用這個函式庫或套件、包括讓使用者知道怎麼操作、包括讓管理者知道這個軟體的規格和價值是什麼。

而就最傳統的文件,當然莫過寫成文字去描述,可能是 Markdown 格式、也可能是 Office 或其他文書處理軟體的檔案格式。然而多數的程式設計師,對於寫這類文件都感到頭疼,因為去寫文件常常是一個枯燥的過程,且不容易得到回饋,天曉得到底有誰會去看這些文件,多數寫文件都是為了主管而寫,好像寫了文件就不怕有人離職或是相關知識遺失,但為了這類目的寫出來的文件都沒什麼人在看。除了這個問題,這類文件會遇到的另一個問題正如昨天所述,當文件的內容越來越複雜、越來越龐大時,維護的成本就會越高,若是沒有持續關注,可能就會逐漸過期、失效。

所以若是寫給其他開發者看的這類文件、甚至寫給組織內部成員有關這個軟體規格的內容,為了提高程式設計師編寫的動力、讓文件的可用性變高、以及較低的維護成本,最近這類文件都漸漸變成以程式碼或是類似的形式存在。像是「需求實例化」(Specification by Example)就是強調要建立可執行的需求規格、活的說明文件,利用編寫驗收測試(可參考 ATDD)或是編寫描述行為的測試(可參考 BDD),利用測試去作為規格文件與使用文件,讓驗收者可以讀測試裡的描述暸解規格與行為、讓開發者透過測試暸解如何使用等等。

另外,在專案裡建立類似 examples 的目錄,並在下面放置該專案於在各個情境的使用範例,讓開發者去暸解該如何使用,我認為這也是一種文件,而且對於開發者來說,有時候直接讀程式碼會比文字還要來得更快暸解與吸收。

而這類文件形式的好處,正是在其可執行性以及會跟著列入版本控制,一旦可以執行,我們就可以透過其中結果判定這類文件裡面的資訊是否還有效,並可以搭配自動化去隨時驗證,這樣文件的可用性就會持續被維護著。

結果說要論文件,剛講完其中一部分篇幅就差不多了[^1],所以我才說真的是一籮筐的議題呢。總之,能讓第三者暸解軟體且易於維護的文件,就是好文件。其他的部分,我們之後有機會再聊聊吧!


1: 所以我把標題從原本的「論文件」改成「淺論文件」了。(艸)


上一篇
為什麼強如大神也會寫糞扣
下一篇
學會調整自身狀況也是軟體開發很重要的事
系列文
軟體開發隨筆談31

尚未有邦友留言

立即登入留言