読者です 読者をやめる 読者になる 読者になる

【DDDメモ】ドキュメントの作成

蒸溜ドキュメント

エリック・エヴァンスのドメイン駆動設計 P.425

 簡潔なドキュメントを書き、コアドメインとコアを構成する要素間の主要な相互作用を記述すること。
 ドキュメントを独立させることに伴う通常のリスクは、すべてここにも該当する。

  1. ドキュメントが維持されないかもしれない。
  2. ドキュメントが読まれないかもしれない
  3. 情報源が増えることで、複雑さを切り開くというドキュメント本来の目的が失われるかもしれない。

 これらのリスクを制限する最善の方法は、ミニマリズムに徹することである。ありふれた詳細からは距離を取り、中心的な抽象とその相互作用に集中すれば、ドキュメントが古くなるのを遅らせることができる。
 チームの日技術系のメンバが理解できるようにドキュメントを書くこと。そのドキュメントは、誰もが知っているべきことの輪郭を描く共通の見方として、また、チーム全員がモデルとコードの探求を始める際の指針として使用すること。

 ソースコードではなくドキュメントが仕様の一部を示していることがあるが、それを機能を知らないエンジニアや非エンジニアが理解できるように翻訳する作業や、コーディングに落とす時間のすべてが価値を産まない時間となり無駄になる。できるだけ全てはソースコードに記述し、それを抽象化したり非エンジニアが理解できる粒度にするのがドキュメントである。
 だからこそ必要なものになるし、更新もされるものになる。ソースコードもドキュメントも使われないものは全て無駄。そういう観点で、本当に必要な物以外は削ぎ落とせる眼を持ちたい。