這篇推薦給想做好documentation，但卻常常失望於document不知道要怎麼解決outdated問題的，或者懷疑人生到底該不該做的人。
這篇不會跟你討論怎麼寫好的document，而主要是探討document的目的是什麼。
通篇文章不是在討論怎麼寫document，而是在討論我們為什麼要寫document？
首先講者想跟大家討論一個主題：到底需不需要documentation？這個問題會浮起在於：
第一，根據敏捷開發宣言，似乎documentation並不那麼重要。
Working software over comprehensive documentation — Agile Manifesto
第二，大家常常會有一些迷思：document一下就outdated了，寫幹嘛？我在寫扣就是在寫document；document是要寫UML嗎？
以上種種原因導致大家對寫document到底有沒有意義這件事存疑。
講者說了其實她也無法幫你回答這個問題，因為其實還是很看狀況。所以講者整篇是想聊聊：「document的實際能帶來的效益與用途為何」？爾後你便可以自己思考在你的狀況下是否需要documentation。
首先必須要確定的一件事情是：**絕對不要為了流程而去寫document。**這是什麼意思？例如你寫document只是為了讓你老闆知道你有在做事。或者你也不知道為什麼要寫，只是因為這是開發流程一部分而已。
再來講者列出了五點寫document的目的：
創造共同的理解
人腦不像電腦，即使同一句話在不同人腦袋裡都有不同的解釋，所以document一部分的目的就是讓大家取得共識，確認大家的理解是相同的。舉例來說會議記錄（meeting minutes）就是個很常見的為此目的而誕生的document。
講者講到一個有趣的練習是，你可以先講一個概念給整個團隊，然後大家分別回去寫下自己的理解，而後來看大家的理解是否相同。這個好處是你可以知道誰的思路可能比較不一樣，或者你講解的方式是不是大家都能有相同的理解。
另外講者也講到一個叫共同理解牆的想法，就是可以把這些大家已經確定取得共識的討論畫成圖放在牆上，以便大家隨時都可以看到，也可以讓新人快速融入。
理解複雜的問題
對於複雜或不直觀的事物，我們必須要記錄下來，為了提醒未來的自己或幫助他人理解這個複雜的東西。而如果它是有一些重要的歷史演進過程的話，也必須要跟著記錄下來，因為很多時候人們會無法理解為何現狀是如何，所以必須要花點心力把迭代的過程與原因也寫下來才能幫助理解。
講者說在他們團隊裡也會把一塊一塊系統component畫出來變成widget，最終這堆widgets可以變成widget kits。當他們想還原某個系統的演進過程或討論時，就可以把這些component拿出來用。
創造同理的環境
像上述寫的就是技術決策者去同理工程師們，記錄做決策的原因幫助他們理解緣由。
工程師也要去同理工程師。
有人叫這個「同理優先開發（Empathy Driven Development，sorry我真的不知道怎麼翻譯這個XD）」，就是你要寫出有同理心的code，記錄一些comment，或提供一些背景知識。因為有句話說「沒有引導跟文件的軟體開發，就是在散撥焦慮」，而這件事特別發生在senior對待junior的溝通上。
工程師也更要同理產品人員。
而工程師雖然常常抱怨產品經理（PM）：根本就不懂軟體，或寫的需求文件很爛。但其實我們也沒花很多心力去嘗試讓PM理解軟體，或者我們自己寫的document也不怎麼好理解。
工程師也必須要同理其他外部技術人員。
我們外人看都覺得別人做的事情很簡單，但你又沒親自做過你們怎麼知道到底是真的很簡單還是有很大部分事情你沒看到。
幫助未來的自己做決定
上面也講到寫document很大一部分是幫助未來的你了解過去的context，以便你有更多的資訊量幫助做出更好的決定。很多時候我們會遇到一個問題是，不清楚當初做決策的原因是為何？所以導致我們也有兩條路（1）盲目的繼續接受這個決策 （2）盲目的改變這個決策。但無論何者都不太理想，所以我們最好還是能好好的把事情記錄下來。
講者給了一個簡單的template我們要怎麼記錄決策內容，可以見此範例。有個重點是，一定要把問題寫清楚，而不是只寫解法，因為我們看得到解法但可能不知原先的問題為何。
幫助解決問題
當你嘗試嘗試畫出你遇到的問題時，往往能同時激發你的左右腦因而達到找到問題解法的目的。所以某部分的寫document是為了釐清思路與幫助思考。而這些docuemnt你也無須留下來，因為他只是幫助你整理思路的一個途徑而已。
很多人會覺得這個的解法就是去自動化documentation，但就她自己的經驗自動化的document都不是很成功，要馬太細，要馬太抽象，其實都不是真正有必要記錄下來的事情，她也很難從中抓住重點。
她覺得out-dated無論如何都是一種必然，因為所有與軟體執行無關的東西，在某種程度上都會out-dated。她列出了幾個想法幫助減少out-dated。
最後講者總結了一下就她來說，哪些部分會寫document：
而這些的目的都只是為了幫助有效的人與人之間的溝通。回到最初的問題，即使是敏捷開發的流程，你也必須要寫docuement。
Do something today that future self will thank you for. — Birgitta Boeckeler
自己蠻喜歡這篇演講的，感覺不少地方也有些共鳴。
我自己是個很喜歡寫document的人，因為我喜歡靠documentation來整理我的思緒，document寫的好對我來說也是非常大的成就感（就跟寫code一樣）。但是對於怎麼處理會out-dated這件事情，我也一直沒有很好的想法。或許我就是講者提的那種，寫document寫久了很懷疑人生到底要怎麼讓他保持up-to-date的人。
而且document其實是那種，大家都知道有document很重要，但是大部分人不喜歡寫的東西。一部分是其實寫document很花心力，但是當資源不足的時候很難投資時間在上面，如果你有時間寫document可能還不如多花時間把code寫好少出bug或少欠一些技術債。
另一方面是document的discovery也是很困難的事情，雖然演講中沒提到（也不是演講的重點），但對我來說要如何讓大家有visibility知道有哪些東西是被記錄下來的其實也是很困難的事情。
Document out-dated的現象在快速發展的公司特別的明顯，常常花費心力寫的document過了幾個月就整個都不一樣了。舉個常見的例子是關於我們的產品需求文件（Product Requirement Document，PRD），通常一個feature上線之後會迭代個四五才會比較穩定，但可能半年之內就會一直改一直改，但如果不寫一個總的PRD，大家就必須花非常多的時間把每一個版本都從頭看到尾才能真的理解內容，這個真的是個非常頭痛的問題。雖然我不是PM不是寫PRD的人，但是同樣狀況可以套用在系統架構上，我們之前寫的document也是非常容易out-dated，覺得非常苦惱。
雖然講者講了一些作法，但我覺得up-to-date還是很困難的事情，特別是當你負責的東西越來越多的時候，的確很難同時維護所有的東西。
我對於同理這部份特別有感觸。我覺得大家在寫document的時候，我看到的都是「寫下我想寫的東西」，但其實更重要的是要去想「觀眾想看到什麼東西」。（前幾天有一篇就是在講這件事：如何寫好document）很多junior在寫docs的共同問題就是，會寫下太多的技術細節，因為寫的人往往想的是「我要把document寫好，盡量記錄的越詳細越好」。但一個讀者來說，太快進入這些細節卻是很容易抓不到重點在哪裡，完全無法幫助理解。同樣這件事帶來的壞處也是很容易out-dated，因為技術細節總是改來改去的。所以寫document其實就是一個練習同理非常好的機會。
我覺得寫文章跟寫docs一樣，其實都是幫助未來的自己，留下一點思考的足跡，以便你未來回顧與檢討用。這也是為什麼你會看到這篇文章的原因XD。
最後我其實蠻喜歡講者最後講的：「Do something today that future self will thank you for. 」。我覺得這件事不只套用在寫document，投資自己，或者在做決定的時候，其實都是很好的格言。
作者Birgitta Böckeler是在一家技術顧問公司Thoughtworks的工程師，看了一下她的主頁，一樣是有蠻多有趣的演講主題：例如pair programming，怎麼做codebase handover，有興趣的人可以看看。
iThome鐵人賽
看影片追技術