プロジェクトの開発規模が大きくなってくると設計書の可視化が必要になってくる。 どう管理するか検討した結果、GitLabのHandbookのガイドを参考にするのが良いと思い、開発ドキュメントのWebサイトを作成した。
リポジトリ
開発ドキュメントのWebサイト
memoir-handbook-dot-memoir-review.an.r.appspot.com
調査
最初は以下の4つの方向性で設計書の可視化を検討した
- ①. Design Doc
- ②. Architecture Decision Records
- ③. Wikiにまとめる
- ④. Git管理したWebサイトを作成する
①のDesign Docや②のArchitecture Decision Records（ADR）は必要な情報を漏らさず記録する重要なドキュメンテーションのテクニックである。
なので上記を学ぶことは必須事項だとして、そのドキュメント管理をどうするかの調査を続けた。
候補としては、③ or ④の選択があったが、調査中に見つけたGitLab HandbookのWiki handbooks don't scaleの項目を読み、
運用ルールを定めてGitでWebサイトを管理することで、上記の①、②の要素を含んだドキュメント管理が行えると思い、④で実装する決定をした。
実装
GitLab Handbookのガイドを参考に実装
GitLab Handbookのガイドの以下を参考にした
ドキュメンテーションの参考
以下を参考にした
- Chromium ProjectsのDesign Documents
- デザインドックで学ぶデザインドック
- ユビーが長期に渡ってソフトウェアを進化させ続けるためのドキュメンテーションプラクティス
- ゆめみオープン・ハンドブック
使用したツール一覧
以下を使用してWebサイトを作成
docsify
ドキュメント静的サイトジェネレーター。ビルド不要で表示できる。
記事の追加はMarkdownを追加/編集のみでOK。
また、プラグインを導入することで様々な拡張が行える。
今回は以下のプラグインを採用している。
- Full text search
- サイト内のフルテキスト検索が行える
- docsify-copy-code
- コードブロックにコピーボタンを追加
- docsify-edit-on-github
- webページから直接GitHubの編集画面に遷移できる
他にも、docusaurus も候補として挙がっていたが、こちらはオールインワンで初めから全ての機能を持っている反面、docusaurusの機能を把握して編集を行う必要があったので、今回は気軽に扱えるdocsifyを採用した。
textlint
textlintは文章を設定したルールに沿って記載しているか判定してくれるlinterです。
実行すると以下のように、ルールに沿っていない箇所を検出して指摘してくれる。
様々なtextlintルールが存在するが、今回は以下の記事を参考にSmartHRが公開しているプリセットを、そのまま採用した。
textlintをGitHub ActionsでPush毎にチェックする運用にしている。
ドキュメントの内容
サイドメニューの構成
サイドメニューの構成は以下の通り
Handbookの編集ガイド
誰でも編集が可能なようにガイドを記載
■ Handbookを編集する
https://memoir-handbook-dot-memoir-review.an.r.appspot.com/#/guide/01-local
記事の内容は以下を参考に作成
GitLabだとWeb IDEがあるのかーと思い移行するか悩んだが、GitHubでもCodespacesみたいな感じでVSCodeで直接修正できるようになる可能性もあるかなと思い、今回はGitHubのまま実装した。
単語集
主に以下の用途で記事を作成
- プロジェクト特有の固有名詞を記載
- 表記ゆれの対策
■ 単語集
https://memoir-handbook-dot-memoir-review.an.r.appspot.com/#/word
各機能の設計
各機能の設計を記載
通知
各通知の設計を記載
運用
ステージング環境と本番環境
開発ドキュメントのWebサイトには、ステージング環境と本番環境 が存在する。
運用ルールの差分は以下の通り
| 環境 | ステージング環境 | 本番環境 |
|---|---|---|
| デプロイタイミング | mainブランチにマージされたとき | GitHubのtagをPushしたとき |
| 記載内容 | リリース予定の機能も記載される | リリースされている機能のみ記載される |
| URL | https://wheatandcat.github.io/memoir-handbook/#/ | https://memoir-handbook-dot-memoir-review.an.r.appspot.com/#/ |
■ ステージング環境と本番環境の運用ルール
https://memoir-handbook-dot-memoir-review.an.r.appspot.com/#/guide/index?id=ステージング環境と本番環境の運用ルール
今後の新規機能の開発フロー
新規機能の開発フローは改めてドキュメントに記載する予定だが、現状は以下を想定している。
- ①. 新規機能を検討
- ②. memoir-handbookにissueを作成して機能の設計をADRで記載
- ③. memoir-handbookでブランチを作成、②のissueの内容で修正してPull Requestを作成
- ④. ③のPull Requestを元に各開発リポジトリにissueを作成
- ⑤. ④のissue作成の設計を進めて③の整合性を確認して、必要があれば修正。問題が無ければ③をmainブランチにマージしてステージング環境に反映
- ⑥. ④のissueの開発を行う
- ⑦. ⑥で③との整合性が取れなくなった場合は都度修正
- ⑧. ④のissueの開発が完了
- ⑨. ③の機能がリリースされたタイミングでmemoir-handbookのtagを新規に作成して、本番環境に反映
まとめ
個人開発だとドキュメンテーションは手を抜くことが多かった。
ただ、今までの経験だと後々後悔する事が多かったので、今回は初めから開発フローにドキュメンテーションまで含める運用にしてみた。後は運用してみて改善していく予定なので情報が溜まったら、また記事にしようと思います。
