【開発】【設計】DesignDoc - j-komatsu/myCheatSheet GitHub Wiki

DesignDoc（デザインドキュメント）について

DesignDocとは

読み方: デザインドキュメント

概要: DesignDoc（デザインドキュメント）は、ソフトウェア開発において、システムや機能の設計内容を詳細に記述した文書です。

用途と特徴

項目	内容
目的	システムや機能の設計内容を明確化し、関係者間の共通理解を促進する。
特徴	- 設計の背景や目的を明確化- 技術的な詳細やトレードオフの記録- 将来的な保守や拡張の指針となる
MD利用有無	Markdown形式での記述が一般的で、視覚的に整理しやすい。

ツール一覧

DesignDocを作成・管理する際に使用される代表的なツールを紹介します。

ツール	読み方	用途	Markdown対応	特徴
Confluence	コンフルエンス	ナレッジ共有・ドキュメント管理	×	リッチテキストエディタを採用し、チームでの共同編集が可能
Kibela	キベラ	ナレッジ共有・社内Wiki	○	Markdown対応でエンジニア向けの情報共有に最適
Notion	ノーション	ドキュメント・データ管理	○	マークダウンをサポートし、タスク管理やデータベース管理も可能
Obsidian	オブシディアン	Markdownベースのノート管理	○	ローカル環境で動作し、プライベートなドキュメント管理に最適
MkDocs	エムケイドックス	静的サイト生成	○	Markdownで記述した文書をHTMLに変換し、ドキュメントサイトを作成可能
Docusaurus	ドキュサウルス	静的サイト生成	○	Reactベースのドキュメント管理ツールで、Markdownを活用可能
Miro	ミロ	オンラインホワイトボード	×	図やフローチャート、リアルタイムのブレインストーミングに特化
Lucidchart	ルシッドチャート	図やフローチャート作成	×	UIデザインやプロセス図を作成でき、チームコラボレーション向け
PlantUML	プラントユーエムエル	UML図作成	○	UML図をコードで記述可能で、設計図の自動生成が可能
Swagger	スワッガー	API設計	○	OpenAPI仕様に基づき、REST APIの設計・ドキュメント化が可能
Postman	ポストマン	APIテスト	×	APIのテストや設計、モック作成に適している

各ツールの詳細

1. Confluence（コンフルエンス）

Atlassianが提供するナレッジ管理ツール。
リッチテキストエディタを採用し、WYSIWYG形式での編集が可能。
チームの情報共有に最適。
Markdownには対応していないが、プラグインを利用すれば対応可能。

2. Kibela（キベラ）

Markdownに完全対応した日本発のナレッジ共有ツール。
GitHubとの連携が容易で、エンジニアに人気。
タグ付けやグループ分けができ、情報整理がしやすい。

3. Notion（ノーション）

ドキュメント、タスク管理、データベース機能を備えたオールインワンツール。
Markdownのインポート・エクスポートに対応。
チームコラボレーション機能が豊富。

4. Obsidian（オブシディアン）

ローカル環境で動作するMarkdownベースのノートアプリ。
プラグインを追加することで機能を拡張可能。
プライバシー重視のユーザー向け。

5. MkDocs（エムケイドックス） / Docusaurus（ドキュサウルス）

Markdownを元にドキュメントサイトを生成する静的サイトジェネレーター。
MkDocs: シンプルで軽量、静的な技術文書向け。
Docusaurus: Reactを活用し、カスタマイズ性が高い。

6. Miro（ミロ） / Lucidchart（ルシッドチャート）

Miro: オンラインでホワイトボードを共有し、ブレインストーミングやUX設計に活用可能。
Lucidchart: プロセスフローやネットワーク図などの作成が容易。

7. PlantUML（プラントユーエムエル）

UML図をコードで記述できるツール。
GitHubやJiraとの連携が可能。
設計の自動化に貢献。

8. Swagger（スワッガー） / Postman（ポストマン）

Swagger（OpenAPI）: REST APIの設計、ドキュメント自動生成。
Postman: APIのテストやモック作成に特化。
- APIリクエストの作成・実行: GET, POST, PUT, DELETE などのHTTPリクエストを簡単に作成・実行可能。
- コレクション機能: APIリクエストをグループ化して管理できる。
- 環境変数の利用: テスト環境や本番環境で異なる設定を簡単に切り替えられる。
- スクリプトによるテスト自動化: JavaScriptベースのスクリプトでレスポンスの検証が可能。
- Mock Server 機能: APIが未完成の状態でもテストを進められる。
- Swagger（OpenAPI）との統合: OpenAPI仕様をインポートしてAPIドキュメントとして活用可能。
Swagger（OpenAPI）: REST APIの設計、ドキュメント自動生成。
Postman: APIのテストやモック作成に特化。

DesignDocの構成要素

DesignDocは以下の要素で構成されます。

タイトルと概要: ドキュメントのタイトルと、設計対象の概要を記述します。
背景と目的: なぜこの設計が必要か、その背景と目的を説明します。
要件定義: 機能要件や非機能要件を明確にします。
設計詳細: システムのアーキテクチャやデータフロー、使用する技術などの詳細を記述します。
トレードオフと代替案: 検討した他の方法や、それらを採用しなかった理由を記載します。
テスト計画: どのようにテストを行うか、その計画を示します。
リスクと課題: 想定されるリスクや現在の課題を列挙します。

作成手順

以下の手順でDesignDocを作成します。

情報収集: 要件や制約条件を関係者から収集します。
構成の決定: 上記の構成要素に基づき、ドキュメントのアウトラインを作成します。
詳細記述: 各セクションに詳細な情報を記述します。
レビュー: 関係者にドキュメントを共有し、フィードバックをもらいます。
修正と更新: フィードバックを反映し、ドキュメントを更新します。

実装例

以下に、簡単なDesignDocのサンプルを示します。

タイトルと概要

タイトル: ユーザー認証機能の設計

概要: 本ドキュメントは、新規に導入するユーザー認証機能の設計内容を記述します。

背景と目的

現在のシステムでは、ユーザー認証が不十分であり、セキュリティリスクが高まっています。そこで、安全性の高い認証機能を導入し、ユーザーの信頼性を向上させることを目的とします。

要件定義

機能要件:
- ユーザー登録
- ログイン
- パスワードリセット
非機能要件:
- パスワードの暗号化
- 多要素認証の導入

設計詳細

以下に、システムのアーキテクチャ図を示します。

graph TD;
  A[ユーザー] --> B[認証サーバー];
  B --> C[データベース];
  B --> D[多要素認証サービス];

トレードオフと代替案

代替案1: 外部認証サービスの利用
- メリット: 実装コストの削減
- デメリット: カスタマイズ性の低下
代替案2: 現行システムの改修
- メリット: 既存資産の活用
- デメリット: セキュリティ強度の不足

テスト計画

単体テスト: 各機能の動作確認
結合テスト: システム全体の連携確認
負荷テスト: 高負荷時の性能確認

リスクと課題

リスク: 新機能導入による既存機能への影響
課題: ユーザーへの周知と教育

追加: DesignDocの実際の適用例

1. 新規システム開発の設計

例: ECサイトの注文管理システム
目的: スケーラブルな設計を実現し、将来的な拡張を容易にする
設計要素:
- データフロー（注文受付 → 決済処理 → 在庫更新）
- API設計（注文API、決済API、通知API）
- エラーハンドリング（決済失敗時のリトライ処理）

2. 既存システムのリファクタリング

例: レガシーコードのモダナイズ
目的: 技術的負債を解消し、メンテナンス性を向上
設計要素:
- コードのモジュール化（責務分離、関数の再利用）
- パフォーマンス改善（キャッシュ導入、データベース最適化）
- テスト戦略（単体テスト・結合テストの強化）

3. APIの設計とドキュメント化

例: RESTful APIの開発
目的: 外部システムとの連携を円滑にする
設計要素:
- エンドポイント設計（GET /users, POST /orders）
- 認証方式（JWT、OAuth2.0）
- レスポンスフォーマット（JSON, エラーハンドリング）
- 自動生成ドキュメント（Swagger, OpenAPI）

まとめ

DesignDocは、ソフトウェア開発における設計内容を明確化し、関係者間の共通理解を促進する重要なドキュメントです。このように、DesignDocは様々な開発シーンで活用され、プロジェクトの成功に大きく貢献します。