write-readme

Write Readme

Overview

README ファイルは、マーケティング文書や API のダンプではなく、実際のユーザー向けの簡潔なパッケージドキュメントとして作成してください。このリポジトリ全体で使われている構成に倣い、サンプルは本番環境を意識したものにし、散文では不自然な手動の改行を避けてください。

Workflow

1. ドラフトを書く前に、パッケージの API と、少なくとも 1〜2 個の関連パッケージの README を読んでください。
2. 理想のパッケージではなく、現時点で存在するとおりにパッケージを文書化してください。
3. インストールセクションが終わったら、すぐに現実的な本番環境での利用例から始めてください。
4. 主要な各機能を、具体的な例とともに説明してください。
5. 最後に、エコシステム内のリンク、外部の関連作品、およびライセンス情報を記載してください。

Structure

特別なパッケージ固有の理由がない限り、次のセクション順を使用してください。

1. # short package-name（例：@remix-run/fetch-router ではなく fetch-router）
2. 導入文：パッケージが何をするのか、なぜ存在するのかを 1〜2 文で説明
3. ## Features：主な特長をフラットな箇条書きで示す
4. ## Installation
5. ## Usage：パッケージを文脈の中で示す、本番環境に近い例
6. 主要な機能ごとに 1 セクション。それぞれに焦点を絞った例を含める
7. ## Related Packages
8. ## Related Work
9. ## License

Rules

• インストールは必ず次で始めてください。

npm i remix

• パッケージがサードパーティの依存関係またはピア依存関係を必要とする場合は、インストールセクションの remix の後に明示的に記載してください。
• 利用例では、@remix-run/... ではなく remix/... からインポートしてください。
• 最初の例は、できるだけ小さなスニペットではなく、実際のアプリケーションコードのように見えるものにしてください。
• 機能セクションでは、パッケージの主要な機能を実践的にどう使うかを示してください。必要に応じて、機能ごとに 1 つの例を用意してください。
• 文章は簡潔に保ってください。文の途中で行の長さを揃えるために不自然な位置で段落を折り返さないでください。
• 長い説明のブロックよりも、フラットな箇条書きと短い段落を優先してください。
• Related Packages では、モノレポ内の関連する Remix パッケージを指してください。
• ファイル間またはパッケージ間のリポジトリリンクには、生成されたドキュメントにコピーされても README の内容が機能するように、完全な GitHub URL を使用してください。同一ドキュメント内のアンカーと README の自己リンクは相対パスのままにしてください。
• Related Work では、読者がパッケージの位置づけを理解する助けとなる外部のライブラリ、仕様、標準、先行事例を指してください。
• License では、リポジトリの標準的な表記とリンクを使用してください。

Checklist

• 導入文は、パッケージを 1〜2 文で説明しているか？
• 機能リストは、パッケージの主要な価値をすばやく示しているか？
• インストールセクションは npm i remix を使用しているか？
• 主要な利用例は、現実的な本番環境のシナリオを示しているか？
• 主要な各機能に例があるか？
• README は Related Packages、Related Work、License で終わっているか？
• 不自然な手動の改行がなく、文章が自然に読めるか？