この記事は Akerun - Qiita Advent Calendar 2024 - Qiita の18日目の記事です。
こんにちは、Miwa Akerun Technologiesが運営する賃貸住宅管理システムの開発チームでエンジニアをしている ps-yu1129 - Qiita です。
私の所属するチームでは、設計や開発に関するドキュメントのうち、フロードキュメントを GitHub Discussions、ストックドキュメントを GitHub の Wiki にまとめています。この運用をチームで約1年間続けてきたため、振り返りたいと思います。
- 当初のドキュメントについての課題感
- GitHub Discussions および Wiki に集約することにした理由
- GitHub Discussions の運用について
- GitHub Wiki の運用について
- 運用してみての振り返り
当初のドキュメントについての課題感
ドキュメントについての取り決めがない時は、設計資料や相談事項を Confluence に書いていましたが、下記のような課題がありました。
- フロードキュメントなのか、ストックドキュメントがどれなのかの区別がつかない
- 知りたい情報がまとまっておらず、情報にたどり着くのに時間がかかる
- どのような議論があり、どういう意思決定があって今の設計になったのかが不明
そこで、フロードキュメントを GitHub Discussions に記載し、ストックドキュメントを GitHub の Wiki に記載することにしました。
GitHub Discussions および Wiki に集約することにした理由
GitHub のサービス上にドキュメントを集約することにした一つ目の理由は、ドキュメント管理サービスが変わっても使い続けられるという点です。Photosynth の開発部では、過去に別のドキュメント管理サービスを使用していましたが、現在は Confluence を使用しています。今後ドキュメント管理サービスの移行があるかはわかりませんが、少なくとも、GitHub から別のコード管理サービスに移行する可能性の方が低いと思います。
二つ目の理由は、開発者向けの情報を一つのサービスに集約できるためです。ドキュメントもソースコードも GitHub 上で管理できるため、サービスの行き来をしなくて済みます。
GitHub Discussions の運用について
GitHub Discussions はリポジトリの設定から有効化できます。（詳しくは リポジトリの GitHub Discussions を有効化または無効化する - GitHub Docsを参照）有効化すると、いくつかデフォルトでカテゴリが用意されていますが、これに加えて設計用に ADR（Architecture Decision Record）というカテゴリを追加しています。
カテゴリを追加した理由は、スレッド作成者によって記載内容にバラツキがあることや、最終的に何が決定された内容なのかがわかりづらいという問題があったためです。カテゴリの作成は、リポジトリの /.github/DISCUSSION_TEMPLATE/ 配下に yaml ファイルを追加することでできます。（詳細は ディスカッション カテゴリ フォームの作成 - GitHub Docs を参照）
実際に使用しているテンプレートは下記の通りです。
title: "[ADR] " body: - type: markdown attributes: value: | 1. 下書き - コメント募集をする場合には、「代替案」を記載する - 提案をする場合には「決定」を記載する 2. コメント募集(オプション) 3. 提案 4. 承認 or 却下 or 代替 5. 決定 - type: dropdown id: status attributes: label: ステータス options: - draft - rfc - proposed - accepted - rejected - deprecated - superseded validations: required: true - type: textarea id: context attributes: label: コンテキスト description: どのような状況でこの決定を迫られているのか？ placeholder: | 例えば、この決定をする前にどのような問題があったのか？ また、この決定をする前にどのような選択肢があったのか？ validations: required: true - type: textarea id: decision attributes: label: 決定 description: 決定した内容と決定がなされた理由 placeholder: | Bad: サービス間に用いるのは非同期メッセージが最善の選択肢だと思う Good: サービス間に非同期メッセージを使用する。なぜなら... - type: textarea id: alternative attributes: label: 代替案 description: 決定したい内容について意見を募集したい場合に記載する placeholder: | - 案1) - 案2) - 案3) - type: textarea id: consequences attributes: label: 影響 description: 「決定」の影響について記載する。 placeholder: | - メリット1) - メリット2) - デメリット1) - デメリット2) - type: textarea id: compliance attributes: label: 順守 description: 「決定」の評価・統制方法について - type: textarea id: notes attributes: label: 備考 description: | - オリジナルの著者 - 承認日 - 承認者 - 変更点 - type: textarea id: review-points attributes: label: 設計レビュー観点 description: | 設計時のレビュー観点。 レビュアーに参照してもらうため、中身は変更しないこと。 value: | - リソースのライフサイクルが明確になっているか - etc...
「設計レビュー観点」の項目については、設計段階からバグを排除するための施策として追加したものになります。レビュアーだけでなく、設計者もレビュー観点に記載の項目が設計から漏れていないかのチェックができるため、重宝しています。
上記のテンプレートを用いて、例えば以下について議論しています。
- 要件を実現するためにどこにどのような変更を加える必要があるかの検討
- テーブル設計
- ライブラリの選定
なお、Discussions がクローズした後に変更が必要になった場合であっても、クローズした Discussions の修正は行いません。修正が必要になった場合は、別途 Discussions を立てて議論を行います。
GitHub Wiki の運用について
GitHub Discussions で議論して決まったことや、設計や開発に関してストックドキュメントとして残したいものについては Wiki に記載しています。例えば、下記のようなものです。
- 実装方針の説明
- テーブル設計の規約
- OpenAPI で管理している API ドキュメントの書き方
また、内容に変更があった場合には、その都度更新するようにしています。
運用してみての振り返り
約1年ほど運用してきましたが、GitHub Discussions や Wiki に情報が集約されているため、体感ですがドキュメントを探す時間が少なくなったように思います。
また、仕様や技術選定について、なぜその意思決定を行なったのかの理由が議論を含めてわかるため、変更を加える際に設計意図を確認でき、調査時間の短縮になっています。とはいえ、当初設計したものから変更を加える機会はまだ少ないため、ありがたみを感じる場面は今後増えてくるのかなと思います。
ドキュメントの管理に悩んでいる方は、GitHub Discussions や Wiki を検討してみてはいかがでしょうか。
株式会社フォトシンスでは、一緒にプロダクトを成長させる様々なレイヤのエンジニアを募集しています。 photosynth.co.jp Akerunにご興味のある方はこちらから akerun.com
