メインコンテンツまでスキップ

ドキュメント執筆ガイド

このガイドでは、River Review プロジェクトのドキュメントを執筆する際のスタイル標準を定める。

言語ポリシー​

  • 日本語版（.md）をソース・オブ・トゥルースとする。
  • 英語版を追加する場合は同名の .en.md を同じディレクトリに配置する。
  • 両バージョンの内容がずれた場合は日本語版を優先する。
  • 技術用語は必要に応じて英語も例示する（例: 重要度—severity）。

文体​

  • 本文（段落・説明文）は ですます調 で書く。
  • リスト項目は である調 で書く。
  • 批判的・攻撃的な表現は避ける。

Markdown 書式​

見出し​

  • ページタイトルは # 1つ、以降は階層に応じて ## / ### を使う。
  • 見出しに区切りダッシュを入れる場合は em-dash（—）を使い、前後にスペースを入れない（例: 概要—背景）。

リスト​

  • 箇条書きは - を使う（* や + は使わない）。
  • 入れ子は最大2階層までとする。

コードブロック​

  • コードブロックには必ず言語タグを付ける。
npm run fix:dashes
（出力例や固定テキストはこの形式）
  • インラインコードは バッククォート1つで囲む（例: npm install）。
  • 裸のバッククォートフェンス（言語タグなし）は使わない。

リンク​

  • 内部リンクは相対パスで記述する（例: [CONTRIBUTING.md](CONTRIBUTING.md)）。
  • 外部リンクには必ず表示テキストを付ける。

MDX ファイルの注意点​

  • < および { はコードブロック外では使わない（JSX パーサーがエラーになる）。

ダッシュの扱い​

ルートの CONTRIBUTING.md §「ドキュメントスタイル（ダッシュ）」が SSoT です。要点を以下に再掲します。

  • 文章の区切りには em-dash（—）を使い、前後のスペースは入れない。
  • 数値範囲には en-dash（–）を使う（例: 0.0–1.0）。
  • コードブロックや YAML 値には自動変換を適用しない。
  • ローカルで修正するには npm run fix:dashes を実行する。

正確性​

  • 技術的な内容はコードや動作を確認してから記述する。
  • 未実装・将来予定の機能は「予定」「今後対応」と明示する。
  • スクリーンショットや出力例は実際の動作に基づく。

アクセシビリティ​

  • 画像には代替テキスト（alt 属性）を付ける。
  • 表には見出し行を設ける。
  • 略語の初出には日本語の説明を添える。

レビューと品質チェック​

PR 提出前に以下を確認する。

  • 本文がですます調、リスト項目がである調になっているか。
  • コードブロックに言語タグが付いているか。
  • ダッシュの種類が正しいか（npm run fix:dashes を実行済みか）。
  • 内部リンクが正しいパスを指しているか。
  • 日本語版と英語版（存在する場合）の内容が一致しているか。

貢献​

このガイド自体の改善にも貢献を歓迎します。提案やフィードバックがある場合は、Issue を作成するか、Pull Request を送信してください。

最終更新: 2026年6月3日。