From 20cdf7dc2860f4df3ab2a8965a44d9c602f6d07e Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 9 Feb 2024 22:32:37 +0900 Subject: [PATCH] =?UTF-8?q?=E3=83=95=E3=82=A9=E3=83=AB=E3=83=80=E6=A7=8B?= =?UTF-8?q?=E9=80=A0=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/forMarkdown/README.md | 65 ++++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/documents/forMarkdown/README.md b/documents/forMarkdown/README.md index df1f5349..fa9018d6 100644 --- a/documents/forMarkdown/README.md +++ b/documents/forMarkdown/README.md @@ -8,19 +8,64 @@ pageClass: lang-home footer: ©2015 - 2024 Future Enterprise Coding Standards - Future Corporation --- -Markdownベースの設計ドキュメントの規約です。 +Markdownベースの設計ドキュメントの規約をまとめる。 -システム開発にて利用する設計ドキュメントをMarkdownベースにすることで、コーディングと同じ慣れたツールを用いて、Gitによるバージョン管理、レビュープロセス、CI/CDなどに自動化（静的解析、自動生成）を行いやすくし、ドキュメントを陳腐化させず、俊敏な設計開発を目指します。 +システム開発にて利用する設計ドキュメントをMarkdownベースにすることで、コーディングと同じ慣れたツールを用いて、Gitによるバージョン管理、レビュープロセス、CI/CDなどに自動化（静的解析、自動生成）を行いやすくし、ドキュメントを陳腐化させず、俊敏な設計開発を目指す。 -Markdownに閉じた話では無いが、どういった内容を設計書に記載すべきかは悩むポイントは多いです。 - -本規約では、アプリケーションの種別ごとに記載すべき内容と、それをどのようなMarkdownの構造で記載するかを規約化し、各チームで悩む余地を減らし、注力すべきことに集中できる環境を提供することを目的とします。 +Markdownに限った話では無いが、どういった内容を設計書に記載すべきかは悩むポイントは多い。 +本規約では、アプリケーションの種別ごとに記載すべき内容と、それをどのようなMarkdownの構造で記載するかを規約化し、各チームで悩む余地を減らし、注力すべきことに集中できる環境を提供することを目的とする。 ## 前提 -TODO チーム規模、アプリケーション/ライブラリなど対象、Gitで管理など、 +本規約は以下の前提で作成されている + +- チーム/プロジェクトが3～30名程度規模程度 +- Git（GitHub, GitLab）で管理され、コードと設計書が同一リポジトリで管理される +- システム開発で必要なアプリケーション開発 + +## フォルダ階層 + +リポジトリ直下に `docs` フォルダを作成し、その配下に設計ドキュメントとなるMarkdownファイルを配備する。 + + +次はバックエンド、フロントエンド、インフラのコードをモノリポで管理している例である。 + +```sh +. +├── backend # バックエンド系のコード +├── docs +├── frontend # フロントエンド系のコード +├── infrastructure # インフラ系のコード +``` + +`docs` 配下は以下のルールにしたがった構造を取る。 +- `01_`、`02_` といったプレフィックスを持つ +- 番号には体系をもたせず、必要になったタイミングでインクリメントさせる +- オンボーディングコストを抑えるため、なるべく先頭に新規参画者が欲する情報を配備する + +構成例を次にあげる。 + + + +```sh +docs +├── 01_キャッチアップ # ドメイン知識など抑えておくべき前提知識 +├── 02_環境構築 # +├── 03_開発規約 # GitFlowなど、リリース方式、CI／CD周り +├── 04_ユーザーストーリー # +├── 05_画面レイアウト # Figmaのパスなど +├── 06_画面遷移図 # +├── 07_画面アクション +├── 08_API設計書 # OpenAPIのパス＋各BL設計 +├── 09_データモデル # ERD, テーブル定義 +├── 10_IF設計書 # I/F定義＋受信/送信BL設計 +├── 11_バッチ設計書 # タイマー、イベント起動の非同期処理のBL設計 +├── 12_インフラ設計 # 監視、キャパシティサイジング、コスト +├── ... +└── README.md +``` ## フロントエンド @@ -33,6 +78,14 @@ TODO ## バックエンド +### テーブル定義書 + +A5ER + +### Web API定義書 + +OpenAPI.yamlで記載する + ### Web API設計書 TODO