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

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

docsifyで開発ドキュメントの管理を行う②: 実運用まで

以下のdocsifyで開発ドキュメントの管理を行なう①: 基礎構成の記事の続きです。

docsifyで開発ドキュメントの管理を行う① - ペペロミア & memoir開発ブログ

以下に記載している内容をドキュメント化して実際の開発フローにのせる運用をやってみた。

開発手順のドキュメント化

memoirでの開発手順を以下でドキュメント化した。

https://wheatandcat.github.io/memoir-handbook/#/guide/02-work-procedure

詳細な内容は上記に記載しているので、大枠のフローのみ以下に記載。

  1. memoir-handbookにissueを作成
  2. Architecture Decision Recordsにフォーマットでissueの内容を記載
  3. 作成したissueのIDを元にブランチを作成
  4. issueの内容に沿ってmemoir-handbookを更新開始
  5. 開発側のリポジトリにissueを作成
  6. 4.の修正をmemoir-handbookにPull Request作成 & マージ
  7. 開発開始
  8. 7.の開発中に4.との整合性が取れなくなった場合は都度 Pull Request & マージ
  9. 7.の開発が完了
  10. docs/adr配下にissueの内容をリポジトリに保存

実際に以下のissueで上記のフローを使用して開発を行なったので、そちらを元に解説。

github.com

1. memoir-handbookにissueを作成

memoir-handbookのリポジトリにissueを作成する。

今回は、タイトルを達成したタスクを検索する機能に設定してissueを作成。

2.Architecture Decision Recordsにフォーマットでissueの内容を記載

作成したissueの本文をArchitecture Decision Records(※以下ADR)のフォーマットに合わせて作成する。

ADRについては以下の記事を参考。

今回は、ADRのフォーマットに沿って以下のようにissueの本文を修正した。

## ステータス

提案済

## 文脈、背景や問題点の説明

1年の終りに年間の振り返りができるようにしたい。

現状、週1回の振り返りのみ実行できる構成になっているが、年末や、季節の終りなどの特定のタイミングに絞って振り返りがしたいと思うときがある。

そこで、**達成したタスクを検索する機能**の実装を検討する。


## 決定

menuに**達成したタスクを検索**の項目を追加する。<br/>
以下の項目を入力して検索ができる
 - 開始日時、終了日時
 - 共有メンバー(複数選択が可能)
 - タスクカテゴリー(複数選択が可能)
 - Good、Bad

この機能は、ログイン後のみ使用できる

## 考慮した選択肢

 - 振り返り画面に絞り込みのアイコンを追加する
   - 季節末や年末にしか利用されない想定の機能なので、普段使用する手順に作用しないように実装した方が良さそうなので不採用
 -  各検索項目を4ステップに分けて入力させる
   - 入力の分かりやすさを考慮して以下の画面遷移で入力させる事も考えたが、分かりやすさより、入力の手間のデメリットを考慮して不採用にした
     - ステップ1/4: 開始日時、終了日時
     - ステップ2/4: 共有メンバー
     - ステップ3/4: タスクカテゴリー
     - ステップ4/4: Good、Bad

## 決定結果

 - メリット
   - 1週間の振り返り以外のタイミングでも振り返りが行える 
 - デメリット
   - なし 

3. 作成したissueのIDを元にブランチを作成

以下のドキュメントに沿ってブランチ名を作成する。
https://wheatandcat.github.io/memoir-handbook/#/guide/02-work-procedure?id=ブランチ名の設定

今回は、以下のURLでissueを作成したので、18-search-task でブランチを作成。
https://github.com/wheatandcat/memoir-handbook/issues/18

4. issueの内容に沿ってmemoir-handbookを更新開始

作成したissueの内容に沿ってHandbookを更新を開始する。
以下、5.〜8.までの工程は並列で進めていく。

今回修正したHandbookのPRは以下の通りです。
https://github.com/wheatandcat/memoir-handbook/pull/21/files

以下が上記の修正で作成されたHandbookのページです。
達成したタスクを検索する機能

5. 開発側のリポジトリにissueを作成

Handbookで作成したドキュメント & issueの情報を元に開発側のissueを作成 & 開発の設計を行う。

今回は、上記のissueから以下の開発issueを作成。

6. 4.の修正をmemoir-handbookにPull Request作成 & マージ

memoir-handbookで作成したブランチの修正のPull Requestを作成してmainブランチにマージする。

7. 開発開始

5.で作成したissueの開発を開始する。

8. 7.の開発中に4.との整合性が取れなくなった場合は都度 Pull Request & マージ

実際に開発している中で、4.との整合性が取れなくなった場合は都度ブランチを作成してHandbookを更新する。(以降9.まで4.〜8.の繰り返しで進める)

今回は、以下のbackendの開発中にFirestoreでは同じQuery内でINを複数設定できない仕様があり、それが原因で現状カテゴリー検索項目を複数件指定できないことが判明した。
【backend】達成したタスクを検索する機能

なので、4の工程に戻り、issueの本文とHandbookに以下を追記した。

■ issueの本文

## 決定

menuに**達成したタスクを検索**の項目を追加する。<br/>
以下の項目を入力して検索ができる
 - 開始日時、終了日時
 - 共有メンバー(複数選択が可能)
 - タスクカテゴリー(複数選択は不可能)  // ← 複数選択は可能から、複数選択は不可能に修正
 - Good、Bad

この機能は、ログイン後のみ使用できる

## 考慮した選択肢

 - タスクカテゴリーの複数選択を可能にする   // ← 追加
   - Firestoreのwhere句でIN条件を複数指定する事ができなかったので、複数選択を1つのみにする 

■ Handbookの更新: docs/functions/memoir/02-search.md

## 検索項目

|  項目名  | 内容  | 入力 |
| ---- | ---- | ---- |
|  開始日  | 検索する達成したタスクが発生した開始日 | 日付 |
|  終了日  | 検索する達成したタスクが発生した終了日 | 日付|
|  共有メンバー  | 検索する共有メンバーを選択する | 複数選択 |
|  カテゴリー  | 検索する達成したタスクのカテゴリーを選択する | 1つ選択 |  // ← 追加
|  Good  | 達成したタスクが良い出来事を検索する | ON/OFF |
|  Bad  | 達成したタスクが悪い出来事を検索する | ON/OFF |

9. 7.の開発が完了

8まで仕様のすり合わせが完了している状態で開発が完了してissueはCloseする。 その際に、issueの本文のステータス項目を承認済に修正する。

10. docs/adr配下にissueの内容をリポジトリに保存

docs/adr配下にissueの内容を保存する。
以下の提案書の一覧画面にリンクを追加する。
https://wheatandcat.github.io/memoir-handbook/#/adr/index

今回は、 達成したタスクを検索する機能のissueの対応なので、上記の通り追加して以下のページを作成した。

https://wheatandcat.github.io/memoir-handbook/#/adr/01-search-tasks

これで開発の一通りのフローは完了です。

機能的には以下のようになった。

www.youtube.com

運用ポリシーの追加

運用してみて、必要な項目を以下のページにまとめた。

https://wheatandcat.github.io/memoir-handbook/#/guide/04-policy

詳細な内容は上記に記載しているので、ポリシーの項目のみ以下に記載。

  1. 機能開発はHandbookの開発の手順の通りに進行する
  2. 保守すべきドキュメントはHandbookのみとして、常にHandbookは最新の状態を保つ
  3. 陳腐化しやすい情報は記載せず、仕様はすべて文章化する
  4. 重複した内容を記載しない
  5. 機能設計のドキュメントには必ず "目的" の項目を記載する
  6. 積極的にMarkdownの表現を使用する
  7. 単語集/画面名に記載している単語を積極的に使用する

まとめ

実際にフローの通り開発してみたログとして記事を作成した。
開発の目的や判断の履歴が残ることで、機能拡張の時の思想のブレが減りそうだなと思った。
しばらく、このフローで開発を行なって見るのでナレッジが溜まったら、また記事にしようと思います。