documentation-standards

# Documentation Standards

## 概要

このSkillは、作成されるすべてのMarkdownドキュメントに適用される記述標準を定義します。一貫性のあるドキュメント作成を実現し、可読性と保守性を向上させることを目的としています。

## 責任範囲

このSkillは以下の範囲をカバーします：

- Markdownドキュメントの記述スタイル（言語、敬体/常体、箇条書き形式など）
- ドキュメント構造と見出しの使用方法
- 簡潔で明確な文章表現の原則
- コードとドキュメントの分離方針
- 用語の統一と一貫性の維持
- markdownlint-cli2を使用したドキュメント検証プロセス
- 頻出するmarkdownlintルール違反とその対処方法

## 基本方針

### スタイル

- 日本語で記述する
- 常体で記述する
- 一貫性のあるドキュメント構造にする
- インデントはスペース2個で統一する
- 絵文字の使用は以下の場合に限定する
  - ユーザーから絵文字の使用指示があった場合
  - ドキュメントの見出し（H1〜H3）で視認性を高める目的で使用する場合
- 絵文字を使用する場合は、見出し（H1〜H3）のみに使用し、本文中では使用しない
- 図は`Mermaid`を使用して作成し、外部画像の埋め込みは避ける

### 簡潔に記述する

- 冗長な表現を避け、必要な情報のみを提供する
- 一文を短くし、明確な主語と述語を使用する
- 繰り返しを避け、同じ情報を複数回記載しない
- 箇条書きや表を活用して、情報を整理する
- 情報を削らず、表現を工夫する

### 要件定義書や仕様書にコード・疑似コードを含めない

- ドキュメントはあくまで要件や仕様を伝えるものであり、実装コードを含めない
- コード例が必要な場合は、別途コードリポジトリやサンプルコードとして提供する
- コード例をドキュメントに含めると、ドキュメントの保守性が低下し、内容が古くなるリスクがある
- ドキュメントは技術的な詳細よりも、要件や仕様の理解に焦点を当てる

### 用語の統一

- 同じ意味を持つ用語は一貫して同じ表現を使用する
- 専門用語や略語は初出時に定義し、必要に応じて注釈を付ける
- ユーザーが必要だと判断した場合は用語集を作成し、ドキュメント全体で参照できるようにする

## ドキュメント検証

- ドキュメントの作成後、`markdownlint-cli2`を使用してドキュメントを検証する
- ユーザーが明示的に指示をしない限り、`--fix`の自動修正オプションは使用しない
- 次のコマンドでMarkdownファイルを検証する
- markdownlint-cli2がインストールされていない場合は、`npx`を使用して実行する
- パスは相対パスを使用すること

**検証コマンド例1:**

```bash
npm markdownlint-cli2 **/*.md
```

**検証コマンド例2:**

```bash
npx markdownlint-cli2 **/*.md
```

### 発生頻度の高いエラー

- 次のルール違反が特に多く発生するため、注意して確認すること

#### 見出し (Headers)

- **MD025 (H1は1ファイルに1つ)**: `H1` (#) はファイルの先頭に1回だけ使用する
- **MD001 (レベルは飛ばさない)**: `H1` → `H2` → `H3` のようにレベルを順に使用する
- **MD003 (スタイルの統一)**: `#` スタイル（ATX）に統一する
- **MD022 (前後に空行)**: 見出し（H1以外）の前後に空行を1行入れる
- **MD024 (同一内容の見出し重複禁止)**: 同じテキストの見出しを複数回使用しないようにする

#### 空行 (Blank Lines)

- **MD012 (連続した空行は不可)**: 空行は1行だけにする
- **MD031, MD032 (ブロック要素の前後)**: コードブロック、リスト、引用などの前後には空行を1行入れる

#### リスト (Lists)

- **MD004 (マーカーの統一)**: 順序なしリストは`-`に統一
- **MD007, MD005 (インデントの統一)**: リストのインデントはスペース2個に統一

#### 書式とスタイル (Formatting)

- **MD010 (タブ不使用)**: インデントにはタブではなくスペースを使用する
- **MD034 (URLの書式)**: URLは `<https://exampl