Webバックエンドチームのドキュメント構造

Overview

長期的な開発、スケーラブルなチーム構築のためにドキュメンテーションは必須。整理されていないと各メンバーがドキュメントを見つけられない、どこに作ればいいかわからないといった問題が発生するため、ドキュメント構造のポリシーが必要である。ここでは現時点の自分が必要だと思うドキュメント構造をまとめる。

想定 - 開発・運用を両方行うWebバックエンドチーム - 継続的に新規開発を行なっている

書かないこと - ドキュメンテーションのツール - ドキュメントを定期的に更新する方法・工夫

更新の優先度付のため、これらは区別しておいたほうがよい。当然外部向けのドキュメントは最新の情報が要求される。

クライアントが自分たちのプロダクトをどう使えばよいかの情報を提供。 swaggerなど別のツールを利用しているならそれのリンクで十分。

アクセスキーの取得方法、その他申請方法など。

連絡先。

開発を進めるために誰がどのプロセスをどう進めるかを明らかにする場所。

例 - メンバーのロール・役割定義 - 開発の進め方の定義 - ミーティング

新規開発や仕様変更、システム改善などのドキュメントをまとめるところ。終わったらメンテナンスしない前提。

例 - バックグラウンド - プロジェクトを達成するための設計 - スケジューリング

システム変更した部分に関して、プロジェクトが完了したら次節のシステムのドキュメントに反映する。プロジェクト段階では現状との差分だけ設計することが多々ある。

稼働しているシステムの詳細情報。

例 - システム全体の設計 - データ設計 - 各コンポーネントの設計(API, DBなど) - 環境情報(APIのURL、DBのホスト名等)

開発者間で揃えた方がよいルール。セットアップやAPI毎の詳細な設計などはGithubに書いた方が管理しやすいかも。

例 - ブランチ戦略 - レビュールール - コーディングルール - クラス命名規則 - エラーハンドリングの方針

どんな種類のテストを誰(CI/担当者)がどのタイミング(PR作成時/マージ後/リリース前/リリース後)で実施しているか明確にする。開発者内で認識が揃っていないとテストピラミッドを構築するのが難しくなる。事故の再発防止を考えるときにどこのテストを補強すべきかといった判断に使える。

リリース作業方法の共有、リリース履歴の検索などに使う。

例 - リリース方法(ロールバック方法含む) - リリース履歴

こういうアラートが出たらこういうアクションをするというのがある程度定まっていると属人化を防ぎやすい。

例 - モニタリングツールの説明 - モニタリング項目 - アラート検知時の対応手順

なんでも置けるスペース。どこにおけばいいかわからないドキュメントや提案段階のドキュメントを気軽に置けると良い。