01.基本規定

本規定は、プロジェクト内のドキュメント作成における基本的なルールを定めます。

Note

本規定は、ドキュメント全体の体系を定めるものです。 ナビゲーションやレビューに関する詳細は、以下の各規定を参照してください。

• 02.ナビゲーション規定
• 03.レビュー規定

1. 基本方針

• 明確性: ドキュメントは、対象読者が容易に理解できるよう、明確かつ簡潔な言葉で記述します。
• 一貫性: 用語、書式、構造などにおいて、プロジェクト全体で一貫性を保ちます。
• 保守性: 将来的な変更や更新が容易に行えるよう、構造化されたドキュメントを作成します。
• 自己完結性: 可能な限り、このドキュメントサイト内で情報が完結することを目指します。

2. ファイルとフォルダ

2.1. 命名規則

• ファイル形式: Markdown形式 (.md) を使用します。
• エンコーディング: UTF-8 (BOMなし) を使用します。
• 命名規則:
  • ファイル名およびフォルダ名は、半角英数字、ハイフン (-)、アンダースコア (_) を基本とします。スペースは使用しません。
  • 主要なドキュメントやカテゴリフォルダには、01_のような2桁の数字プレフィックスを付け、順序を明確にします。
  • 内容の理解を助けるため、ファイル名に日本語を含めることもできます。（例: 01_認証機能.md）
  • 各カテゴリフォルダの案内ページとなるファイル名は README.md に統一します。

2.2. ファイル名と要求IDの関係

• ファイル名は、人間がその内容を理解しやすいように命名します。（例: 01_認証機能.md）
• 要求ID (REQ-XXX-X.Xなど) は、原則としてファイル名には含めません。
• 要求IDは、ファイルの中身の見出しや本文で定義・参照します。

3. 要求IDによるトレーサビリティ

プロジェクト全体の成果物の追跡可能性を確保するため、要求IDを定義し、その利用ルールを定めます。

3.1. 命名規則

• 要求仕様書で定義される各要件には、プロジェクト内で一意のIDを付与します。
• フォーマット: [種別]-[カテゴリ]-[メジャー番号].[マイナー番号]
  • 種別: REQ(機能要件), NFR(非機能要件), UI(UI/UX要件)など。
  • カテゴリ: 機能を示す3〜4文字の略称 (例: AUTH, USER, POST)。
  • メジャー番号: 機能の大きな塊を表す番号 (例: 1, 2, 3...)。
  • マイナー番号: メジャー番号に属する詳細な要求を表す番号 (例: 0, 1, 2...)。.0 は親となる概要要求に使うことを推奨。
• 具体例:
  • REQ-AUTH-1.0: ログイン機能全体の要求。
  • REQ-AUTH-1.1: パスワードポリシーに関する要求。
  • REQ-AUTH-1.2: アカウントロックに関する要求。

3.2. ドキュメント内での利用

• 定義: 要求仕様書でIDを定義する箇所には、<a id="REQ-AUTH-1.0"></a> のようにHTMLアンカーを埋め込みます。
  • または、見出しに { #REQ-AUTH-1.0 } のようにIDを付与します。（推奨）
  • 例: ### 1.1. パスワードポリシー { #REQ-AUTH-1.1 }
• 参照: 他のMarkdownドキュメントからIDを参照する場合は、必ずアンカーへのリンクを作成します。
  • 例: この設計は、[REQ-AUTH-1.1](../../01_要求仕様/01_機能要件/01_認証機能.md#REQ-AUTH-1.1)を実現する。

注意

見出しにIDを付与する { #... } 形式を利用するには、mkdocs.yml の markdown_extensions に attr_list が設定されている必要があります。

Note

ソースコードや自動テストコード内での要求IDの記述ルールについては、それぞれ 04.コーディング規定 および 05.リリース規定 を参照してください。

4. Markdownの記述スタイル

4.1. 基本構造

各ドキュメントファイルは、一貫性と機械的な処理のしやすさを考慮し、以下の基本構造に従います。

---
# (任意) このページのメタデータ (YAML Front Matter)
title: サイドバーに表示するカスタムタイトル
...
---

# (必須) H1見出し (ドキュメントタイトル)
この見出しが、ページ内で最も大きなタイトルとして表示されます。

• Front Matter (任意):
  • ページのタイトルをmkdocs.ymlのnavで定義されたものから変更したい場合など、特別なメタデータを定義する場合にのみ使用します。
  • YAML形式で---の間に記述します。詳細はMaterial for MkDocs 公式ドキュメントを参照してください。
• H1見出し (必須):
  • 全てのドキュメントは、Front Matterの直後（またはファイルの先頭）に、必ず#から始まるH1見出しを1つだけ含める必要があります。
  • このH1見出しが、そのページの主題を示すメインタイトルとなります。

4.2. スタイルガイド

!!! info "コーディング規定への移管" Markdownの具体的な記述スタイル（見出し、コードブロック、注釈など）に関する詳細なルールは、03.Markdown コーディング規約 に集約されています。 ドキュメントを記述する際は、そちらを参照してください。