Yuichi Murata's Engineering Blog

グローバル・エンジニアリング・チームをつくる

ドキュメントが無い!? TDDD があなたを救う

なんでドキュメントがないんだ

ドキュメントはとても大事だ。誰だって分かっている。ではどうしてこんなにもドキュメントが不足しているのだろうか。

f:id:yuichi1004:20201130230337j:plain
Photo by Annie Spratt on Unsplash

エンジニアというのは本来怠け者である。仕事を片付けるための最も最適な方法を見つけようとする。彼らが注意を向けるのは製品価値をユーザーに届けることだ。自然と必要最小限のドキュメントを整備しようとする。 ドキュメンテーションファースト

典型的なプロジェクトの反応はこうだ。誰かが「いいかげん、ドキュメントを整備しようぜ」と言い出す。プロジェクトメンバーはドキュメントを纏め始める。最終的にそれなりのドキュメントが整備される。だがこのアプローチは完璧ではない。

1 つめに、設計当時の文脈はドキュメント化するタイミングでは失われていることがある。「ここなんだけど、なんでこんな設計なんだっけ?」「あー、それはもう退職したヤツが設計した箇所だからなぁ」これは典型的な文脈を失った例である。もしあなたがその設計者だったとしても、一年前の設計上の意思決定の理由を正確に覚えていられるだろうか?(自分は忘れっぽいので大抵ここで困る)

2 つめに、ドキュメントを後回しにするプロセスは必要なドキュメントをすべてカバーすることができない。ドキュメント化を一生懸命におこなう活動が一段落したとしよう。そして、プロジェクトは通常の開発フェーズに戻る。するとあなたは、再びドキュメント化されていない情報を見つけるだろう。必要な情報はそのたびに足していけばいいと言うかもしれない。確かに一理ある。だが、これは辛い作業だ。 設計をしてから時間が経つほど、ドキュメンテーションは辛くなる。「ドキュメントを後回しにする」プロセスよりも「ドキュメントをまず作る」プロセスを作るべきではないか?

Ticket Driven Design Doc (TDDD)

さてここで、チケット駆動設計ドキュメンテーション (TDDD) の話をすることになる。自分はここ数年このやり方をチームに導入してきたが、このアプローチはまずドキュメンテーションをする文化をチームに根付かせるために良いやり方だと考えている。

おそらくあなたも何かしらのチケットシステムを使って開発プロセスを回していると思う。ここで「ドキュメント作成」と「ドキュメントレビュー」をワークフローに組み込んでしまうのである。以下は典型的な Agile プロジェクトで使うストーリーのワークフローに組み込んだ例である。

f:id:yuichi1004:20201130230341p:plain
典型的な TDDD ワークフロー。ワークフローは開発者たちにドキュメントの執筆とレビューを開発前に実施することを強制する

すべての開発チケットがドキュメンテーションをプロセスの一部として持つことになる。これはエンジニアにどのような変更もドキュメントを書くことを強制する。え、ちょっとまって。ドキュメンテーションをワークフローに組み込むだって?それでドキュメント化を促進するって、当たり前といえば当たり前では?まぁ、そうなのだが、TDDD にはもう一つ重要なポイントがある。

ドキュメントをチケット番号を基準に作り込んでいくのである。以下はドキュメンテーションの例である。

f:id:yuichi1004:20201130230346p:plain
チケット番号化されたドキュメント

これ RFC に似ているねと思ったあなた。そのとおりである。基本的に RFC からアイディアを頂いている。チケット番号化された文章はいくつかの特徴がある。

ドキュメンテーションのステータスと信憑性が明示される

コンフルのようなコラボレーション型のドキュメンテーションツールを使う場合、ステータスの不明確な文章に出くわすことがないだろうか。ドキュメントは下書きかもしれないし、最新ではないかもしれないし、誰にもレビューされていないかもしれないし、最悪な場合は誰かのメモ書きかもしれない。

チケット番号化することで、ドキュメントの状態が明確になる。誰がレビューをして誰が承認したかも明らかになる。

開発項目とドキュメントの対応が明確になる

チケット番号が明確であるため、開発項目とそのドキュメンテーションの対応が明確になる。これはプロジェクトマネジャーにとって、ドキュメンテーションのステータスを追うことができることを意味する。もし誰かがドキュメントを書かずに開発を進めていようものなら、ドキュメントを書いてレビューしてもらうようにツッコむのも簡単だ。

変更点が明確になる

開発チケットとドキュメントが対応するので、ドキュメントは変更点を明確にする。マスタードキュメントを継続的にアップデートする別のアプローチを考えてみよう。レビュアーはどこが今回の変更点で、どこが既に開発済みなのかパット見では分からないだろう。チケット番号化されたドキュメントはエンジニアに「変更点」を書くよう促す。これはレビューを実施する立場にとってみるとやりやすい。QAチームに取ってみても、変更点からテストケースへの影響を知ることができるだろう。

ドキュメントがリンクされる

RFC のようにドキュメントをリンクすることが出来る。もしあなたが機能を単純に追加しようとしているのであれば、ドキュメントを「更新」としてリンクすることができる。もしあなたが新機能で昔の機能を置き換えようとしているのなら、「廃止 (Obsolete)」としてリンクすることもできるだろう。あなたはリンクによってどのような「変更」をもたらそうとしているのか明示できるのだ。

ドキュメントの読者にとってみると、なにか新しい変更がある場合にはリンクをたどることも出来る。

TDDD の弱点とその克服方法

TDDD はお世辞にも完璧とは言えない。TDDD は変更点のドキュメンテーションを強制するゆえに、マスタードキュメントを継続更新することは得意としていない。API 仕様書を想定してみよう。TDDD のアプローチは API 仕様書を常に最新化することを保証しないだろう。

こうした弱点を補完する必要があるだろう。いくつかのドキュメンテーション自動化ツール (例えば doxygen や swagger など) は最新の情報を基にドキュメントを自動生成できるので、こうした自動化ツールはひとつの解決策たりうる。

TDDD はドキュメンテーションファースト文化を促進する

上に述べた通り TDDD は完璧な解決策とは言えない。だが、TDDD はドキュメントをまず書く文化を促進する。これは開発プロセスのもっとも重要な部分だ。TDDD はドキュメントの信ぴょう性を明確にすることもできる。

自分はこのアプローチをつかって過去のチームマネジメントでいくつかの成功体験を持っている。そして今、似たようなアプローチを他の活動にも転用を試みている。近い将来、そうした試みについても書いてみたいと思う。

原文:

yuichi-murata.medium.com