READMEファイルの書き方

READMEファイルに盛り込むべき情報

アプリケーションのREADMEファイルを作成するにあたっては、複数のアプリケーションで使用できる標準形式を考えて、標準形式に従ってテンプレートを作成する必要があります。

以下のようにREADMEに盛り込むべきテンプレートを示しておきます。

要素	説明
プロジェクトタイトル	プロジェクトタイトルかそれに類するものを必ず含めておきます
プロジェクト の説明	プロジェクトの一環として「プロジェクトの作成方法」セクションを含めておきます
目次	全主要セクションの一覧
インストール方法	明確なインストール方法を順次、提供できるように記載します
使用方法	基本的なコマンドなどを記載します。サポートポータルの詳細ドキュメントやチュートリアルへのリンクを記載しておきます
構成方法	構成が必要なソフトウェアプロジェクトの場合、各構成オプションの内容を詳しく説明する構成ファイルやコマンドの引数の例を記載しておきます
依存関係	必要な依存関係を記載しておきます。インストールするための指示やスクリプトを記載しておきます
トラブルシューティング	よくある問題点と解決方法を記載しておきます
貢献者	このプロジェクトに貢献している方々などを記載しておきます
教訓	開発中に習得した教訓を、READMEファイルを使って共有しておきます
ライセンス	ソフトウェアのライセンスのタイプとライセンスへのリンクを明記しておきます
連絡先	サポートや問い合わせのための連絡先情報(メールアドレスやサポートポータルへのリンク)を盛り込む

まとめ

多くの技術ドキュメントと同様、READMEファイルがじっくりと読まれることは少ないです。

そのため、ざっと読み流しできるように、わかりやすい言葉、説明的な見出し、論理的な構造を使って、専門的な用語は使わないようにします。

アプリケーションの使用方法を明確に示すように、コードスニペットやスクリーンショットなどの例を豊富に記載しておきます。

アプリケーションが複雑な場合は特に、ドキュメント、問題点、サポート・トレーニングのコンテンツを公開します。

ドキュメント計画だけでなく、プロジェクトの全体計画を含める必要があります。
製品リリースの直前に、READMEファイル全体を慌てて1から作成することのように、リリースの数日前から繰り返しアップデートができるようにしておくようにしましょう。