この記事はMOSH Advent Calendar 2023の10日目の記事です。

プロダクティビティーチームの@soartec-labです。

前回の記事では、プロダクト開発における「学習のためのアウトプット」と「収益のためのアウトプット」を分けて捉えることで効率的な開発を目指すアプローチについて紹介しました。

この記事では、開発組織の生産性を向上するためのドキュメンテーション文化についてアプローチしている内容を紹介します。

背景

開発チーム全体での課題として以下の課題が発信されることが多く、私も1人の開発者として同様の課題を持っていました。

開発中の過去の経緯や仕様の理解が難しく時間がかかってしまう
仕様確認やシステム理解が手探りになり開発体験が悪い
複数人がそれぞれ別の目的で1つのリポジトリを更新するので情報を効率的に把握したい

目的

これらの問題を解決する事でナレッジを蓄積し自律したチーム開発を実現することを目指しました。

組織拡大や新入社員のオンボーディングに備えて情報を整理したい
過去の意思決定を振り返り可能にして継続的な改善を促進する
技術的な意志決定の透明性を高め開発チーム全体のシステム理解度を向上させる
組織内で開発に関する情報を共有し個々で判断できる質とスピードを向上させ自走できるようにする

やったこと

開発のアウトプットとしてADR、Design Docの2種類のドキュメンテーションを書くことを開発プロセスに導入しました。

ADR（Architecture Decision Records）

ADRは実装方針の変更や新しいツール、技術の導入などアーキテクチャに関わる意思決定を残します。ADRとDesign Docを分けることで、機能開発に閉じた内容と全体に関わるシステムにおける重要な意思決定が混ざることを避けています。軽微なものはPRのDescriptionに書くことにしています。

書籍Design It!では設計をタンジブルにするアクティビティの1つとして紹介されています。

Design Doc（Design Document）

Design Docは機能や設計に焦点を当て検討した内容を明文化します。

実装方針の変更や新しいツール、技術の導入などアーキテクチャに関わる意思決定があった場合には別途ADRを書きます。そのためDesign Docの中でアーキテクチャの変更があった場合はADRを書いて参照することもあります。

書籍Googleのソフトウェアエンジニアリングではドキュメンテーションとして詳細に説明されています。

以下のサイトでも詳細に説明されております。

ドキュメントのテンプレート

実際の開発では以下のようなテンプレートを用意し、こちらをベースにドキュメンテーションを行っています。

ADR テンプレート

# 目的
解決したい課題はXXX。

# 背景
解決する問題の背景やチームの状況などの戦略。

# 制約事項
ライブラリや設計の変更におけるトレードオフやできない事とその理由。

# 内容
- 採用した内容
- 検討して採用しなかった内容

# 影響範囲
ADRの決定が及ぼす可能性のある影響範囲。

# 参考リンク
ADRに関連する情報や参考にした資料へのリンク。

# Author
ADRを提案・作成した個人またはチームの名前。

Design Doc テンプレート

# 目的
# ゴール

解決したい課題はXXX。

# ノンゴール
XXXについてはこのドキュメントのスコープ外です。

# 背景
解決する問題の背景やチームの状況などの戦略。

# 制約事項
ライブラリや設計の変更におけるトレードオフやできない事とその理由。

# 解決する課題
具体的な解決すべき課題。

# 課題に対するソリューション
- 採用した内容
  - API設計、DB設計なども含めて詳細に
- 検討して採用しなかった内容

# 参考リンク
Design Docに関連する情報や参考にした資料へのリンク。

# Author
Design Docを提案・作成した個人またはチームの名前。

まとめ

9月ごろから導入を進めており社内ではポジティブなフィードバックをが多いです。また週次で書いたドキュメントを共有しておりナレッジ共有の文化も少しずつ醸成されてきたと感じております。
今はドキュメンテーションに慣れていく段階だと捉えておりアウトプットの中から学んでいければと考えておりますが、ゆくゆくは技術的な意思決定を振り返ったり過去の経緯をベースとした改善に役立てることができる経験を組織的に積んでいきたいと考えています。