GitHubのドキュメントでは、READMEはプロジェクトがなぜ役立つのか、何ができるのか、どう使えるのかを伝えるファイルで、ライセンスや投稿ガイドラインとともにプロジェクトへの期待を伝えるものとされています(GitHub Docs)。
英語のREADMEの見出しテンプレート
| 見出し | 書くこと | 例文 |
|---|---|---|
| # Project name | 名前と1行の説明 | A tiny CLI to rename photos by date. |
| ## Features | 主な機能を箇条書き | - Renames files using EXIF dates |
| ## Requirements | 必要な環境 | Node.js 20 or later |
| ## Installation | インストール手順 | Install the package with npm: |
| ## Usage | 使い方とコマンド例 | Run the command in your photo folder: |
| ## Configuration | 設定項目 | You can change the date format in config.json. |
| ## Contributing | 貢献の方法 | Pull requests are welcome. For major changes, please open an issue first. |
| ## License | ライセンス | This project is licensed under the MIT License. |
READMEでよく使う表現
| 英語 | 意味 |
|---|---|
| To get started, clone the repository. | 始めるには、リポジトリをクローンします。 |
| Make sure you have Docker installed. | Dockerがインストールされていることを確認してください。 |
| The following command starts the dev server. | 次のコマンドで開発サーバーが起動します。 |
| This project is still under active development. | このプロジェクトは現在も開発中です。 |
| See CONTRIBUTING.md for details. | 詳しくはCONTRIBUTING.mdを参照してください。 |
| If you find a bug, please open an issue. | バグを見つけたら、Issueを作成してください。 |
書くときのコツ
- 手順は命令形で短く:「Run」「Install」「Copy」で始めます。
- 主語の「We」は使いすぎない。「This library ...」「The tool ...」で書くと客観的になります。
- コマンドはそのままコピーできるようにコードブロックに入れます。
日本語版と英語版を両方用意するには
よくあるのは、英語の README.md をメインにして、日本語版を README.ja.md として置き、それぞれの先頭に「English | 日本語」のリンクを並べる方法です。英語版を先に更新し、日本語版が古くなっていないかを定期的に確認します。
Devlingoで開発現場の英語を1日10フレーズ
Gambit StudioのDevlingo(English for Devs)は、開発者のための英語フレーズアプリです。デイリースタンドアップ、コードレビュー、Slack、プルリクエスト、バグ報告、面接など12カテゴリに3,600以上のフレーズを収録し、1日10個ずつ、使う場面と発音ガイド、例文つきで学べます。ホーム画面ウィジェットには今日のフレーズが表示されます。画面表示は英語などで、日本語には対応していません。