はじめに
どうもKizukuです．
みなさんハッカソンの参加経験はありますか？
ハッカソンの時にドキュメント整備はしていますか？
チーム開発をする場合はハッカソンであってもドキュメントを書いておくほうが何かと便利だったりします．
そこで，この記事ではハッカソンで使えるドキュメント整備術について書きたいと思います．
今回はDesign Docの回です．
他のドキュメントに関しては，こちらを参照してください
(この記事内で出てくるハッカソンは2,3日程度の短期間のハッカソンのことを指します．1ヶ月以上の長期ハッカソンの場合は，もっとちゃんとしたドキュメントを書きましょう)
対読者
- ドキュメントをあまり書いたことがない人
- ハッカソン大好きな人
- チーム開発好きな人
Design Docとは
Design Docは，日本語でいう「設計書」に相当します．
アプリケーションの具体的な定義をDesign Docに事前に記述しておくことで，開発フェーズに入った際に，開発者同士が最低限のコミュニケーションで効率的に開発に集中できます．このアプローチは，チームメンバー間の認識の違いによる作業の出戻りを防ぎ，効率的な開発を実現することができます．
また，プロジェクト全体の工数を把握しやすくなるため，時間制限のあるハッカソンのような環境では，残り時間で優先すべき機能や実装可能な機能の選定が容易になります．
記述すべき内容
Design Docの書き方には，いくつかの流派がありますが，一例を紹介します．
この例は，機能ごとにDesign Docを書いていく方法になります．
タイトル
実装したい機能のDesign Docのタイトルを書きます．
概要
実装したい機能の概要を簡潔に書きます
詳細
実装したい機能の詳細を書きます．
機能が満たすべき具体的な要件や条件が明確になるように書いてください．
書くべき内容としては，正常系の処理のフロー，異常系の処理のフロー，その他の特記事項等です．
注意点としては，何が何にどういう処理を行うのかを明確に書くことです．
(日本語では，主語や目的語が省略されていても意味が通る文になることが多いので，意識して書く方がいいです．)
例：バックエンドは，正常にリクエストを処理できた場合にはステータスコード200とリクエストの内容をクライアントに返す．
シーケンス図
処理の流れをシーケンス図を用いて記述します．
正常系の場合と異常系の場合を合わせて，記述します．
シーケンス図を記述するツールとしてはdraw.ioやAstah，PlantUMLなどがあります．
僕のおすすめは，無料でWeb上で書くことができるdraw.ioを用いてそのリンクを埋め込む方式か，Design Doc内に直接書くことができるMermaidを使用してマークダウン内に直接コードブロックとして記述する方式です．以下のサンプルではMermaidを用いて記述しています．
ER図
この機能に関連するデータベースの定義をER図を用いて記述します．
エンティティ同士の関連等を明確にして記述します．
使用するツールに関しては，シーケンス図の時と同じような選択肢が挙げられるので省略します．
スキーマ
リクエストやレスポンスの型とかを定義しておきます
スキーマの定義はopenAPIやprotobufなどを用いて行うのが良いと思います．
個人的には，protobufで書くのがおすすめ．(yamlはあまり書きたくない...)
スキーマ駆動開発の時も，protobufは大活躍するので，ぜひお試しください．
Tips
先ほど書いた記述するべき内容をテンプレート化して，自動生成すると楽です．
私は，scaffdogを用いた自動生成をよく使うのでその設定を残しておきます．
---
name: 'DD'
root: '.'
output: './docs/DesignDoc'
ignore: ['.']
questions:
number: 'バージョン管理'
fileName: '何の機能のDDか教えてね'
---
# `{{ inputs.number | rtrim }}_{{ inputs.fileName }}.md`
```markdown
# DesignDoc
## {{ inputs.fileName }}機能について
### 概要
### 詳細
### シーケンス図
### ER図
### スキーマ
執筆日：{{ date "YYYY/MM/DD HH:mm" }}
```(これは一例です)
また，生成時のコマンドもやや複雑になるためMakefileに記述しておくことをお勧めします
##### scaffing
DD_COUNT:=$(shell find docs/DesignDog -type f | wc -l | tr -d ' ')
dd:
npx scaffdog generate DD --output 'docs/DesignDog' --answer 'number:${DD_COUNT}'
make ddを実行することで，{バージョン番号}_{機能名}.mdという形式でADRのファイルを生成することができます．
(この例ではdocs/DesignDogにファイルを生成することを前提としています．)
サンプル
以下にTODOアプリのTODOの登録機能のDesign Docのサンプルを示します．
TODO登録
概要
TODOを登録する機能
詳細
ログイン済みユーザーがTODOを登録する
登録する内容は以下の通りとする．
- TODOの内容
- 期限
ログイン時に発行されたJWTをAuthorizationヘッダーに付与し，そこからユーザーIDを取得しユーザーを識別する．
バックエンドは，正常にリクエストを処理できた場合にはステータスコード200と登録した内容をクライアントに返す．
バックエンドは，リクエストが不正な場合にはステータスコード400をクライアントに返す．
バックエンドは，リクエストに認証情報がない場合やトークンの期限切れの場合にはステータスコード401をクライアントに返す．
クライアントは，リクエストを送りレスポンスのステータスコードが，
400だった場合はエラー表示，
401だった場合は「ログインしてください」の表示，
200の場合は「登録が完了しました」の表示を行う．
シーケンス図
ER図
スキーマ
| エンドポイント | メソッド | 認証 | リクエストJSON | レスポンスJSON |
|---|---|---|---|---|
| /todos/create | POST | 必要 | message CreateTodoRequest { string content = 1; string expired_at = 2; // ISO 8601形式の日付文字列を想定 } |
message CreateTodoResponse { int32 id = 1; string content = 2; bool is_done = 3; int32 user_id = 4; string expired_at = 5; // ISO 8601形式の日付文字列 } |
おわりに
ここまで読んでいただきありがとうございます！
今回紹介したのは，チーム開発における最低限のドキュメントの書き方です．長期間のハッカソンや実際の業務の場合はもっと書くべきことは多くあると思います．
たかがハッカソン，されどハッカソン．
ドキュメントを整備して快適で効率的な開発になるようにしましょう！