ペペロミア & memoir開発ブログ

React Nativeで開発しているペペロミア & memoirの技術系記事を投稿してます

docsifyで開発ドキュメントの管理を行う① :基礎構成

プロジェクトの開発規模が大きくなってくると設計書の可視化が必要になってくる。 どう管理するか検討した結果、GitLabのHandbookのガイドを参考にするのが良いと思い、開発ドキュメントのWebサイトを作成した。

about.gitlab.com

リポジトリ

github.com

開発ドキュメントのWebサイト

memoir-handbook-dot-memoir-review.an.r.appspot.com

調査

最初は以下の4つの方向性で設計書の可視化を検討した

①のDesign Docや②のArchitecture Decision Records(ADR)は必要な情報を漏らさず記録する重要なドキュメンテーションのテクニックである。
なので上記を学ぶことは必須事項だとして、そのドキュメント管理をどうするかの調査を続けた。

候補としては、③ or ④の選択があったが、調査中に見つけたGitLab HandbookのWiki handbooks don't scaleの項目を読み、

about.gitlab.com

運用ルールを定めてGitでWebサイトを管理することで、上記の①、②の要素を含んだドキュメント管理が行えると思い、④で実装する決定をした。

実装

GitLab Handbookのガイドを参考に実装

about.gitlab.com

GitLab Handbookのガイドの以下を参考にした

ドキュメンテーションの参考

以下を参考にした

使用したツール一覧

以下を使用してWebサイトを作成

docsify

docsify.js.org

ドキュメント静的サイトジェネレーター。ビルド不要で表示できる。
記事の追加はMarkdownを追加/編集のみでOK。

また、プラグインを導入することで様々な拡張が行える。
今回は以下のプラグインを採用している。

他にも、docusaurus も候補として挙がっていたが、こちらはオールインワンで初めから全ての機能を持っている反面、docusaurusの機能を把握して編集を行う必要があったので、今回は気軽に扱えるdocsifyを採用した。

textlint

github.com

textlintは文章を設定したルールに沿って記載しているか判定してくれるlinterです。
実行すると以下のように、ルールに沿っていない箇所を検出して指摘してくれる。

f:id:wheatandcat:20220104233420p:plain

様々なtextlintルールが存在するが、今回は以下の記事を参考にSmartHRが公開しているプリセットを、そのまま採用した。

shanaiho.smarthr.co.jp

textlintをGitHub ActionsでPush毎にチェックする運用にしている。

ドキュメントの内容

サイドメニューの構成

サイドメニューの構成は以下の通り

f:id:wheatandcat:20220104234319p:plain:w200

Handbookの編集ガイド

誰でも編集が可能なようにガイドを記載

■ Handbookを編集する
https://memoir-handbook-dot-memoir-review.an.r.appspot.com/#/guide/01-local

記事の内容は以下を参考に作成

about.gitlab.com

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を新規に作成して、本番環境に反映

まとめ

個人開発だとドキュメンテーションは手を抜くことが多かった。
ただ、今までの経験だと後々後悔する事が多かったので、今回は初めから開発フローにドキュメンテーションまで含める運用にしてみた。後は運用してみて改善していく予定なので情報が溜まったら、また記事にしようと思います。