Documentation Standards
概要
このSkillは、作成されるすべてのMarkdownドキュメントに適用される記述標準を定義します。一貫性のあるドキュメント作成を実現し、可読性と保守性を向上させることを目的としています。
責任範囲
このSkillは以下の範囲をカバーします：
- Markdownドキュメントの記述スタイル（言語、敬体/常体、箇条書き形式など）
- ドキュメント構造と見出しの使用方法
- 簡潔で明確な文章表現の原則
- コードとドキュメントの分離方針
- 用語の統一と一貫性の維持
- markdownlint-cli2を使用したドキュメント検証プロセス
- 頻出するmarkdownlintルール違反とその対処方法
基本方針
スタイル
- 日本語で記述する
- 常体で記述する
- 一貫性のあるドキュメント構造にする
- インデントはスペース2個で統一する
- 絵文字の使用は以下の場合に限定する
- ユーザーから絵文字の使用指示があった場合
- ドキュメントの見出し（H1〜H3）で視認性を高める目的で使用する場合
- 絵文字を使用する場合は、見出し（H1〜H3）のみに使用し、本文中では使用しない
- 図は
Mermaidを使用して作成し、外部画像の埋め込みは避ける
簡潔に記述する
- 冗長な表現を避け、必要な情報のみを提供する
- 一文を短くし、明確な主語と述語を使用する
- 繰り返しを避け、同じ情報を複数回記載しない
- 箇条書きや表を活用して、情報を整理する
- 情報を削らず、表現を工夫する
要件定義書や仕様書にコード・疑似コードを含めない
- ドキュメントはあくまで要件や仕様を伝えるものであり、実装コードを含めない
- コード例が必要な場合は、別途コードリポジトリやサンプルコードとして提供する
- コード例をドキュメントに含めると、ドキュメントの保守性が低下し、内容が古くなるリスクがある
- ドキュメントは技術的な詳細よりも、要件や仕様の理解に焦点を当てる
用語の統一
- 同じ意味を持つ用語は一貫して同じ表現を使用する
- 専門用語や略語は初出時に定義し、必要に応じて注釈を付ける
- ユーザーが必要だと判断した場合は用語集を作成し、ドキュメント全体で参照できるようにする
ドキュメント検証
- ドキュメントの作成後、
markdownlint-cli2を使用してドキュメントを検証する
- ユーザーが明示的に指示をしない限り、
--fixの自動修正オプションは使用しない
- 次のコマンドでMarkdownファイルを検証する
- markdownlint-cli2がインストールされていない場合は、
npxを使用して実行する
- パスは相対パスを使用すること
検証コマンド例1:
npm markdownlint-cli2 **/*.md
検証コマンド例2:
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://example.com> のように山括弧で囲む
- MD047 (ファイル末尾の改行): ファイルの末尾は単一の改行で終わらる
除外
以下のエラーは無視する:
- MD013 (行の長さ): 行の長さ上限の設定は無制限とする
- MD033 (HTML不使用):
<br /> などのインラインHTMLは使用可
チェックリスト
ドキュメント作成前
ドキュメント作成中
ドキュメント作成後