Living Documentation by design, with Domain-Driven Designを読んだ
Living Documentation by design, with Domain-Driven Design by Cyrille Martraire [PDF/iPad/Kindle]という電子書籍を読んだ。
leanpubで$0から購入できて、任意の値段で購入できるドキュメンテーションとDDDについての書籍。
ドキュメンテーションもソフトウェア開発のように設計やテストといったパターンやアプローチがあります。 これは以前書いた技術文書をソフトウェア開発する話と似ているところがあります。
ドキュメントに書かれる知識としてGenericなものとSpecificなものがあります。 ドキュメントもソフトウェアと同じように更新され続けるべきですが、 会社やチーム、プロダクトにおけるSpecificな知識には次のような問題が生まれやすいです。
- アクセスできない
- 古すぎる
- フラグメント化してる
- 暗黙的になってる
- 理解できない
- 書かれてない
要はドキュメントはコストがかかるので、更新されなくなって管理されなくなる。
知識は会話から生まれ、知識がstableとなるには時間がかかる。
— azu (@azu_re) March 12, 2017
これは、その知識を記述したドキュメントにはメンテナンスコストが掛かることを示唆してる。#LivingDocumentation
一番良いドキュメントはNo Documentationであることではあるが、これらのドキュメントをどうやって更新され続けるようにするかという戦略、パターン、仕組みなどについて書かれている書籍です。
#LivingDocumentation 良いドキュメンテーションのアプローチは設計が関わる。
— azu (@azu_re) March 12, 2017
急速に変化するプロジェクトに対するドキュメンテーションには設計的なアプローチが必要になる pic.twitter.com/EPBf6yldDs
LivingDocumentationのコア原則
- Reliable
- 信頼性の高いドキュメントを作る2つの方法
- single source of truth
- ソースは一つにする
- reconciliation mechanism
- ソースが複数の場所にあることを認め、それをテストする
- Specifiction by Example
- Low-Effort
- Collaborative
- Conversations over Documentations
- ペアプロは強い
- アクセスできる場所に知識は置く
- Insightful
- 意図を残す
メモ
憶測をドキュメント化しない#LivingDocumentation では逐次的にドキュメントを作っていく。
— azu (@azu_re) March 12, 2017
そのため実際のニーズに基づくドキュメンテーションを行う。
多すぎる情報は、情報が全くないのと同じぐらい役に立たない。#LivingDocumentation
— azu (@azu_re) March 12, 2017
実装のドキュメントはよく変わるため別のアプローチを用意すべき。
— azu (@azu_re) March 15, 2017
戦略のドキュメントは複数のプロジェクト間で共有できるStableなドキュメントすべき。
そのためにプロジェクト特有の細部、変更されやすい所は戦略のドキュメントからは省略する。#LivingDocumentation
この辺は読んでいて、関数型プログラミングの基礎も最近読んだのもあって、ドキュメントとプログラミングの次のような対比が浮かんだ。
戦略というドキュメンテーションは、複数のプロジェクトで共有して参照できるStableなものであるべきで、逆にプロジェクト特有のものは変更の可能性が高いので、戦略からの参照はしない。
- OK: Unstable -> Stable
- NG: Stable -> Unstable
プログラミングにおいて、副作用を持つ部分と副作用を持たない部分をきちんと分離する。 副作用のあるものから純粋なものを参照するが、逆はしない(純粋なものが副作用を持って本末転倒)
- OK: 副作用を持つ関数 -> 純粋な関数
- NG: 純粋な関数 -> 副作用を持つ関数
URLはKnowledge Networkの一部である。
— azu (@azu_re) March 15, 2017
URLでリンクすることは知識を伝達するの有用。
壊れたリンクを回避するためのメカニズムも必要。
参照をするときは、揮発性の高いもの -> 安定したものとなるようにリンクをする。#LivingDocumentation
これ読んでいて一番面白かった話。 よくよく考えると当たり前だけど、文章からソースコードへリンクを貼るとすぐ壊れてしまうので、ソースコードから文章へリンクを貼ったほうが安定するという話。
ソースコードへリンクする際に間接的な方法があるという話も何か面白かった。
#LivingDocumentation ファイルへ直接リンクするんじゃなくて、検索キーワードへ間接的にリンクするという話。 pic.twitter.com/Vo4P3Q0xBi
— azu (@azu_re) March 15, 2017
#LivingDocumentation ドメイン学び方
— azu (@azu_re) March 20, 2017
- 調査結果を壁にはりつけるようにまとめる
- チームについてトレーニングを受ける
- 他の開発者がやってることを半日ぐらい観察する Live-my-Life Sessions
- そのプロダクトのユーザーの行動を見てみる
#LivingDocumentation
— azu (@azu_re) March 20, 2017
これのペアプロ、クロスプログラミング、モブプログラミングのような形は、継続的なドキュメンテーションに役立つ。
ならならFace to Faceでインタラクティブに進む得ることで、お互いの知識を共有でき、
疑問点をすぐに質問することができる
#LivingDocumentation Working collectivelyはトラック係数(Truck Factor)の改善にも役立つ。
— azu (@azu_re) March 20, 2017
単一障害点を避け、情報の集中度を分散できる。
小さなTruck Factorはそのプロジェクトのヒーローであり、
— azu (@azu_re) March 20, 2017
他のチームメイトと共有されていない多くの知識があることを意味している。#LivingDocumentation
ドメイン知識の共有の仕方と単一障害点の話。
#LivingDocumentation
— azu (@azu_re) March 20, 2017
現実的な例の話として、
コードスタイルのLintツールとLint結果の参考文献としてのガイドラインのドキュメントがベストな関係。
ユーザーは必要となるまでそのドキュメントを読まずにすみ、必要なタイミングはLintツールが教えてくれる。
これは読んでいてESLintとかのドキュメントを思い浮かべた。
ガイドラインの"強制"と"推奨"どっちをとるか。
— azu (@azu_re) March 20, 2017
新しく追加されたコードに対しては強制的にエラーとし、
既存のコードベースは、そのガイドラインを違反していることが多いため、警告に留める。#LivingDocumentation
#LivingDocumentation ガイドラインを決めたとしても、そのルールは既存のLintツールではカバーできないことがある。
— azu (@azu_re) March 20, 2017
このときに、コード自体を文書化することでできるかもという話。 annotationある言語は便利だなー pic.twitter.com/6DHksjYiGl
ガイドラインに向かって少しづつに移行する方法
例外はあるが、トラブルシューティングはShameful Documentationの一種とも言える。
— azu (@azu_re) March 20, 2017
そこに書かれているものは、つまり解決されていない問題で修正されていないことを意味してる。#LivingDocumentation
問題を解決するためにトラブルシューティングのようなドキュメントを追加するよりも、その問題を直すために時間を使うべきであるという話#LivingDocumentation
— azu (@azu_re) March 20, 2017
なんでもかんでもトラブルシューティングに逃げてはいけないという話。
ADR(Architecture Decision Records)
重要なアーキテクチャの意思決定のプロセスを記録するフォーマットであるADRというやつがあるのを読んでて初めて知った。
- Blog | Documenting Architecture Decisions | Relevance
- アーキテクチャの意思決定を記録する Lightweight Architecture Decision Records について - Tbpgr Blog
ECMA, TC39 Meeting Notesとかもこれと似たようなフォーマットになっていて、自分がミーティングノートを書いたときも真似ていたので面白かった。
実際の問題の小さな模型でシミュレートする。
— azu (@azu_re) May 7, 2017
頭で理解できる(複雑さの)サイズにし、シミュレートすることで、
後の議論において具体的に参照できるコードが作れる。
これがコミュニケーションツールとして役に立つ#LivingDocumentation pic.twitter.com/GvFG2hZGKy
#LivingDocumentation を取り入れるときは、セオリーの話をするんじゃなくて、シンプルな話として始める pic.twitter.com/sG523au8O9
— azu (@azu_re) May 7, 2017
実践する時のやり方。
Living Documentation by design, with Domain-Driven Design by Cyrille Martraire [PDF/iPad/Kindle] 400-500ページぐらいあって長かったけど読んでいて面白い話が多かったので良かった。 感覚的なものが結構文章化されてので面白い。
一応DDDの本ではあるので、DDDについては簡単に知っておくと読みやすいかも(コード的な話はあんまりないので、概念だけでもよさそう)
あたりを見ておけば大体概念としての事前知識は大丈夫そうな気がする。 後は、IA(情報設計)的なことが好きな人は読むといいのかもしれない。
- 今日からはじめる情報設計 -センスメイキングするための7ステップ | アビー・コバート, 長谷川敦士, 安藤 幸央 |本 | 通販 | Amazon
- アーキテクチャをめぐるたび | Web Scratch
実際のコードからドキュメントを同期するアプローチはアノテーション前提がちょっと強いので簡単には実践できない気はするけど、話として読むといいかなーと思った。
お知らせ欄
JavaScript Primerの書籍版がAmazonで購入できます。
JavaScriptに関する最新情報は週一でJSer.infoを更新しています。
GitHub Sponsorsでの支援を募集しています。