6.0 KiB
6.0 KiB
name, description
| name | description |
|---|---|
| documentation-standards | Markdownドキュメントの記述規約、スタイルガイド、markdownlint検証ルールを定義する。Markdownファイル作成時、README作成時、ドキュメント編集時、またはユーザーがドキュメント標準、Markdown形式、markdownlint、ドキュメントスタイルに言及した際に使用する。 |
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は使用可
チェックリスト
ドキュメント作成前
- ドキュメントの目的と対象読者が明確になっている
- 使用する用語の定義が明確で、一貫性がある
- ドキュメント構造（見出し階層）が論理的に整理されている
ドキュメント作成中
- 日本語・常体で記述しているか
- 絵文字は見出し（H1〜H3）にのみ使用し、本文中には使用していない
- 一文が短く、明確な主語と述語を含んでいる
- 冗長な表現を避け、必要な情報のみを提供している
- 同じ意味を持つ用語を一貫して使用している
- 図はMermaidを使用して作成し、外部画像の埋め込みを避けている
ドキュメント作成後
markdownlint-cli2を使用してドキュメントを検証した- 除外ルール以外のエラーがないか確認した