TL;DR
- 開発チームのドキュメントは、リポジトリの
docs/と Confluence の 2 か所にありました。どちらに何を置くかを、基準として明文化しました - 置き場所を「誰が読むか」で決めました。開発者だけが読むものは
docs/、SRE や PD（プロダクトデザイナー）など開発者以外も読むものは Confluence です - 例外は 1 つだけです。本番のアカウントやリソースの値は、リポジトリに置きません
- 開発者向けの文書を Confluence から
docs/へ移しました。実行スクリプトと手順書を同じ PR で直せるようになり、判断の記録は ADR として起こし直しました - 移した後で手順書を見直し、ほかの作業者でも迷わず追える形に整えました
この記事の対象読者
- リポジトリの docs と社内 Wiki の両方にドキュメントがあり、どちらに書くか迷っている方
- Docs as Code（ドキュメントをコードと同じように管理する）を始めたい方
- 判断の記録を、Wiki から ADR に移したいと考えている方
環境
- リポジトリの
docs/（Markdown。markdownlint で書式を検査） - Confluence（社内 Wiki）
- 題材は、テナント単位でデータを整理する Go のバッチ
背景：ドキュメントが 2 か所にあった
このバッチのドキュメントは、リポジトリの docs/ と Confluence の両方にありました。設計書は docs/ にあり、AWS の環境を操作する手順や、DB のマイグレーションの手順は Confluence にある、という具合です。
2 か所あること自体は、悪いことではありません。読む人が違えば、読みやすい場所も違います。ただ、新しい文書を書くたびにどちらに置くかを考えるのは手間です。そこで、置き場所を決める基準を明文化することにしました。
「誰が読むか」で置き場所を決めた
置き場所の基準は、文書の種類ではなく読む人にしました。
-
開発者だけが読むものは、リポジトリの
docs/に置く - SRE や PD など、開発者以外も読むものは、Confluence に置く
開発者以外の人は、リポジトリを日常的に開きません。Confluence に置けば、開発者以外もいつもの場所で読めます。逆に、開発者だけが読むものは、コードの隣にある方が便利です。
この基準で、文書の種類ごとに置き場所を表にしました。
| 文書の種類 | 置き場所 | 理由 |
|---|---|---|
| 設計（要件・基本・詳細設計、ADR、計測の記録） | docs/ |
コードと密接で、変更をレビューで追いたい |
| ローカル環境の構築、デバッグの方法 | docs/ |
開発者向けで、コードと密接 |
| 各環境の操作 | docs/ |
実行スクリプトと一緒に保守したい。本番の値は Confluence |
| クライアントツールの接続、DB のマイグレーション | docs/ |
開発者だけが読む |
| 本番の運用ルール、実行の記録、リカバリの手順 | Confluence | SRE や PD も読む |
| リリースの手順と記録 | Confluence | SRE や PD も読む |
| インフラの構成（AWS のリソース、本番のアカウントの値） | Confluence | SRE と共有する。本番の値をリポジトリに置かない |
| 開発者以外向けの説明、振り返り | Confluence | 開発者以外も読む |
この表は、リポジトリの README に置いています。迷ったら、まず README を見れば決まります。
例外：本番の値はリポジトリに置かない
「誰が読むか」の基準には、1 つだけ例外を設けました。本番のアカウントやリソースの値は、開発者だけが使うものでもリポジトリに置きません。
各環境を操作する手順書は docs/ にありますが、本番の値が要る箇所は <プロファイル> のような置き換えの印にしています。実際の値は Confluence にあり、SRE と共有しています。
リポジトリは、多くの人がクローンし、履歴も残り続けます。本番の値は、置く場所を限ったほうが管理しやすいからです。
Confluence から docs/ へ移したもの
この基準に沿って、開発者向けの文書を Confluence から docs/ へ移しました。移したのは、次の種類の文書です。
- AWS の各環境を操作する手順
- 処理を実行した後の動作確認の手順
- DB のマイグレーションの手順
- DB のクライアントツールの接続方法
- 処理時間の計測の記録
- 設計の判断の記録（ADR として起こし直した）
手順書とスクリプトを、同じ PR で直せるようになった
環境を操作する手順は、リポジトリの scripts/ にある実行スクリプトと対になっています。手順書とスクリプトが別の場所にあると、片方を直すときに、もう片方を一緒に直す仕組みがありません。
手順書を docs/ に移したことで、スクリプトと手順書を同じ PR で直せるようになりました。レビューでも、スクリプトの変更に手順書の変更が伴っているかを確かめられます。
判断の記録を、ADR に起こし直した
Confluence には、設計上の判断をまとめたページもありました。これを、ADR（Architecture Decision Record。設計の判断を、背景・選択肢・決定・影響の形で残す文書）として docs/ に起こし直しました。
ADR の型に当てはめ直すと、「何を比べて、何を選び、何を諦めたか」を同じ形で読めるようになります。実際、起こし直した 2 つの判断（S3 の削除を別の実行モードに分けたこと、バッチサイズの上限を計測で決めたこと）は、そのまま 1 本の記事にまとめられるほど整理されました。
移した後で、ほかの作業者が追える手順に整えた
文書を移しただけでは、まだ十分ではありませんでした。移した手順書を、自分以外の作業者が読んで追えるかを見直しました。
書いた本人は、手順の前提を頭の中で補ってしまいます。どの環境に対して実行するか、どの権限で実行するか、実行した後に何を確かめれば終わりか。こうした前提を、手順書の中に書き足しました。
Confluence にもページの変更履歴は残ります。ただ、PR のように、変更をレビューしてから反映する流れはありませんでした。docs/ にあれば、手順書の改善も PR として残り、レビューを通ります。
書式は markdownlint でそろえた
docs/ の Markdown は、markdownlint で書式を検査しています。移した文書は、もともと Confluence の書式で書かれていたので、リストの字下げなどがばらばらでした。
移行に合わせて、リストの字下げを 2 スペースにそろえ（markdownlint の ul-indent を 2 に設定）、検査が通る状態にしました。書式の検査があると、書き手が増えても見た目がそろいます。
まとめ
| 決めたこと | 理由 |
|---|---|
| 置き場所を「誰が読むか」で決めた | 開発者以外は、リポジトリを日常的に開かない |
開発者だけが読むものは docs/ に置いた |
コードの隣にあると、変更をレビューで追える |
| 本番の値だけは、リポジトリに置かない | 置く場所を限ったほうが、管理しやすい |
| 手順書をスクリプトと同じリポジトリに置いた | 同じ PR で直せる |
| Wiki の判断の記録を ADR に起こし直した | 「何を比べて、何を選んだか」がはっきりする |
| 移した手順書を、ほかの作業者の目線で見直した | 書いた本人は前提を補ってしまう |
学びは 2 つです。
- 置き場所の基準は「何の文書か」ではなく「誰が読むか」。 文書の種類で分けると、境界の文書で迷います。読む人で分ければ、迷う余地がほとんど無くなります
- 文書をコードの隣に置くと、文書もレビューの対象になる。 手順書の改善や判断の記録が、PR として残ります。ドキュメントを「書いて終わり」にしないための、一番の仕組みでした