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

光是第一章就有許多我不能認同多的內容(吐糟)