Living Documentation by design, with Domain-Driven Design by Cyrille Martraire [PDF/iPad/Kindle]という電子書籍を読んだ。

leanpubで$0から購入できて、任意の値段で購入できるドキュメンテーションとDDDについての書籍。

ドキュメンテーションもソフトウェア開発のように設計やテストといったパターンやアプローチがあります。 これは以前書いた技術文書をソフトウェア開発する話と似ているところがあります。

ドキュメントに書かれる知識としてGenericなものとSpecificなものがあります。 ドキュメントもソフトウェアと同じように更新され続けるべきですが、 会社やチーム、プロダクトにおけるSpecificな知識には次のような問題が生まれやすいです。

  • アクセスできない
  • 古すぎる
  • フラグメント化してる
  • 暗黙的になってる
  • 理解できない
  • 書かれてない

要はドキュメントはコストがかかるので、更新されなくなって管理されなくなる。

一番良いドキュメントはNo Documentationであることではあるが、これらのドキュメントをどうやって更新され続けるようにするかという戦略、パターン、仕組みなどについて書かれている書籍です。

LivingDocumentationのコア原則

  • Reliable
    • 信頼性の高いドキュメントを作る2つの方法
    • single source of truth
      • ソースは一つにする
    • reconciliation mechanism
      • ソースが複数の場所にあることを認め、それをテストする
      • Specifiction by Example
  • Low-Effort
  • Collaborative
    • Conversations over Documentations
    • ペアプロは強い
    • アクセスできる場所に知識は置く
  • Insightful
    • 意図を残す

メモ

この辺は読んでいて、関数型プログラミングの基礎も最近読んだのもあって、ドキュメントとプログラミングの次のような対比が浮かんだ。

戦略というドキュメンテーションは、複数のプロジェクトで共有して参照できるStableなものであるべきで、逆にプロジェクト特有のものは変更の可能性が高いので、戦略からの参照はしない。

  • OK: Unstable -> Stable
  • NG: Stable -> Unstable

プログラミングにおいて、副作用を持つ部分と副作用を持たない部分をきちんと分離する。 副作用のあるものから純粋なものを参照するが、逆はしない(純粋なものが副作用を持って本末転倒)

  • OK: 副作用を持つ関数 -> 純粋な関数
  • NG: 純粋な関数 -> 副作用を持つ関数

これ読んでいて一番面白かった話。 よくよく考えると当たり前だけど、文章からソースコードへリンクを貼るとすぐ壊れてしまうので、ソースコードから文章へリンクを貼ったほうが安定するという話。

ソースコードへリンクする際に間接的な方法があるという話も何か面白かった。

ドメイン知識の共有の仕方と単一障害点の話。

これは読んでいてESLintとかのドキュメントを思い浮かべた。

ガイドラインに向かって少しづつに移行する方法

なんでもかんでもトラブルシューティングに逃げてはいけないという話。

ADR(Architecture Decision Records)

重要なアーキテクチャの意思決定のプロセスを記録するフォーマットであるADRというやつがあるのを読んでて初めて知った。

ECMA, TC39 Meeting Notesとかもこれと似たようなフォーマットになっていて、自分がミーティングノートを書いたときも真似ていたので面白かった。

実践する時のやり方。


Living Documentation by design, with Domain-Driven Design by Cyrille Martraire [PDF/iPad/Kindle] 400-500ページぐらいあって長かったけど読んでいて面白い話が多かったので良かった。 感覚的なものが結構文章化されてので面白い。

一応DDDの本ではあるので、DDDについては簡単に知っておくと読みやすいかも(コード的な話はあんまりないので、概念だけでもよさそう)

あたりを見ておけば大体概念としての事前知識は大丈夫そうな気がする。 後は、IA(情報設計)的なことが好きな人は読むといいのかもしれない。

実際のコードからドキュメントを同期するアプローチはアノテーション前提がちょっと強いので簡単には実践できない気はするけど、話として読むといいかなーと思った。