高品質軟體文件持續分享技術與知識 Living Documentation
Living Documentation: Continuous Knowledge Sharing by Design
在DDD TW Conference 2024天瓏的書攤買的
Chapter 1
活文件(living documentation)一詞出自 Gojko Adzic 的 Specification by Example 一書,是實例規格的許多好處之一。但活文件這個名字不只適用於規格而已。
儲存文件最好的地方是文件描述對象所在地。
開發者的半衰期是3.1年,而程式碼是13年。文件製作必須解決這個不匹配。
資訊墳場 - 知識死在企業知識管理解決方案。以下列項目來說:
- 企業 wiki
- SharePoint
- Microsoft Office 文件
- 共用資料夾
- 搜尋功能不佳的記錄系統與 wiki
這些文件製作方法通常都因很難找到正確資訊或很難更新而失敗。它們偏好唯寫 或只寫一次的文件製作方式。
在一次 Twitter 對話中,Tim Ottinger(@tottinge)問到: 產品類別:“文件墳場”—是否所有文件管理、wiki、SharePoint、共用資料夾都完了? James R. Holmes (@James_R_Holmes) 92 : 有個笑話是你說“在 intranet 裡面”時,對方的反應會是“你是不是叫我去 吃_?"• (注意:不雅字眼已經拿掉;你知道是什麼意思)
文件製作的缺陷 如同劣酒,紙本文件很快老化且讓你頭疼。 —@gojkoadzic 的推文
傳統文件製作的問題 文件是程式設計的瀉藥—經理人認為它對程式設計師很好,但程式設計師討厭它! Gerald Weinberg ’ «Psychology of Computer Programming
光是第一章就有許多我不能認同多的內容(吐糟)