ツ社ではGitHubを利用してソースコード管理を行っています。
ドキュメントや意思決定の資料についてもGitHubでできるだけ管理したいと思いますので、以下を基準に作成をお願いします。
Architectural Decision Records (ADRs)
アーキテクチャをどうやって決めていったのかの履歴を、ADRとして記録していきます。
各リポジトリの /docs/adr フォルダに格納していきます。
テンプレートを /docs/adr/tpl/ADR.md で用意していますので、コピーして使ってください。
ADRを作っていくことで、担当者が変わった時や、みんなが忘れたころに、「これってどうやって決めたっけ？」を思い出せるようにしていきます。
ツ社は、チャットツールを原則禁止しているので、GitHubのissueやDiscussionにメモがあるかもしれませんが、きちんとした文書を残すようにしていきましょう。
システム構成図/アーキテクチャ図
Mermaid記法で Architecture がサポートされましたので、こちらもMarkdownファイルで管理していきます。
データベース設計
データベース設計について、機能追加などの大きい設計変更はADRによって意思決定資料を作成していきます。フラグの追加などの小さい設計変更は、各issueとプルリク等でのやり取りで問題ありません。
DDL（Data Definition Language）作成時においては、テーブルやカラムに説明コメントをつけるようにしてください。Laravelの場合はこのような感じになります。
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
/**
* Run the migrations.
*/
public function up(): void
{
Schema::create('companies', function (Blueprint $table) {
$table->comment('会社情報');
$table->id();
$table->foreignId('user_id')->constrained()->comment('決済可能ユーザーID');
$table->string('name', 100)->comment('会社名');
$table->enum('plan', ['list', 'business', 'plus'])->default('list')->comment('プラン list:リスト、business:ビジネス、plus:ビジネスプラス');
$table->integer('user_count')->default(0)->comment('ユーザー数');
$table->integer('skill_sheet_count')->default(0)->comment('スキルシート受信数');
$table->integer('skill_sheet_list_count')->default(0)->comment('スキルシートリスト数');
$table->timestamps();
$table->softDeletes();
});
}
ER図やテーブル定義書は作成せず、作成後のデータベースに対して SchemaSpyを使って、生成します。
画面設計
画面設計についてはいくつかのツールを利用します。
画面遷移図は、VSCodeの kexi.vscode-uiflow を使って、フロー図を作成します。時にはADRと組み合わせて資料化することがあると思います。
画面デザインについては、Figmaを利用します。画面の表示内容やValidationチェック内容等は、Figmaにメモをつけるか、画面定義書等を作成します。ただ、現状はシステムの規模がそんなに大きくないため、Figma＋issueで対応することが多いです。
API定義書
API定義書はOpenAPIに則って YAML 形式で記述していきます。Swagger UI を VSCode にいれるなどして、ローカルでも確認できるようにします。
その他の設計資料
以下の資料は Markdown （marmaid）または uiflow の形式で記述していきます。
- ファイル設計
- バッチの仕様書
いくつかのバッチ群を構築したり、複雑な仕様でなければ、バッチファイルの先頭で記載してよいです - シーケンス図
外部とのAPI通信時などには記述します - ユースケース
- コーディング規約
- フローチャート
- などなど
どうしてもExcel等のほうが都合がよい場合は、SharePointに格納して、設計資料ファイルからリンクを貼るようにしてください。
ただし、極力避けることにします。
設計資料のチェックについて
自動生成されるものでない限り、すべての設計書はプルリクを行ってチェックしてもらってください。
未来に向けて
いまGitHubを使ってできる資料作成についてのルール作りを最大限やろうとすると、上のようなドキュメント作成ルールになりました。しかし、時代は変化するものです。ADRは昔ならば議事録などで管理されていたものが、チャットとリモートワーク（多拠点開発）が台頭してきたことで、必要に迫られて出てきたものだと感じます。
現状はGitHubで管理できるものを増やそうとするのは「履歴はいるけど、最新版以外は見えなくてよい」ということだと思います。SharePoint等で設計書をバージョンごとに保存してしまうと、検索したときに、いろんなバージョンのファイルが出てきてしまって、設計がデグレする恐れがあることを嫌っているのだと感じます。
新しい情報をキャッチアップした時点で、全社員で共有して、ルールを少しずつ最新化していきましょう。
