実際に手順をたどれるREADMEの書き方

READMEは、新しい読者が最初の有用な行動を取る助けになるべきです。何をするプロジェクトか、自分に関係するかが分かる前に、すべての実装詳細を説明する必要はありません。

得られる結果から説明する

何をするか、誰のためか、重要な制限は何かを説明します。形容詞の羅列より、具体例のほうが役立ちます。目的の説明に役立つなら、動作が分かるスクリーンショットや結果例を上のほうに置いてください。

次に、OS、ランタイムの版、必要なサービスなどの前提条件を示します。任意の連携と、開始に必須のものを区別してください。インストールの途中で初めて必須条件に気づくようにしないでください。

実行すべき順にセットアップ手順を書きます。コマンドをどこで実行し、成功時に何が見えるか説明してください。設定例の仮の値を明示し、本物の認証情報は絶対に入れません。

クリーンなチェックアウトなど、初期状態から手順を試します。自分の機器に未記載のツールがあるために動くコマンドは、説明不足です。最も簡単な対応手順の下に、任意のバリエーションを置きます。

実行、確認、更新に使う主なコマンドを加えます。専門的な内容をすべて冒頭に入れるより、詳細文書へリンクしてください。必要に応じて問題を報告する正式な場所やライセンスも示します。

MeatPadでプロジェクトファイルの近くにREADMEを編集し、公開先でMarkdownの表示を確認します。リポジトリの実際のパスでリンクや画像を確かめてください。セットアップが変わるときは同じ変更でREADMEも更新し、配布される版と初回手順を一致させます。

一つのメモから始めましょう。MeatPadは、メモ、Markdown、プロジェクトファイルのためのローカルな作業環境をMacに用意します。アカウントは必要ありません。