READMEで伝える力：成果物を読んでもらう文章術

READMEは何のためにあるか

READMEは、成果物を見に来た人へ「これは何か」を伝える入口です。

コードを読む前に、目的・使い方・工夫点が分かるREADMEがあると、成果物の価値が伝わりやすくなります。

基本構成

悪い例

Todoアプリです。

良い例

学習予定を忘れないためのTodoアプリです。
スマホでも入力しやすいように、フォームを大きくしました。

注意点

技術名を並べるだけでなく、なぜ使ったかを書きます。読み手は、コード全体を読む前に判断します。

第三者が確認できるREADME

# Study Log

学習時間を記録し、週ごとに振り返るアプリです。

## Demo
公開URLとテスト用の操作手順

## 主な機能
- 記録の追加
- 週別の集計

## 技術選定
小規模な試作のため、ブラウザ保存から開始しました。

## 確認方法
インストール、起動、テストのコマンド

成功例は、初めて見る人が目的を理解し、動作または起動方法を確認できるREADMEです。失敗例は、技術バッジだけを並べ、URLが切れていたり、環境変数や前提条件を書かなかったりすることです。

秘密鍵、実際のパスワード、個人情報はREADMEへ書きません。チーム制作や教材ベースなら、自分の担当範囲と元資料も明記します。

確認問題

READMEに「Node.jsを使用」とだけ書いて、起動できるでしょうか。対応version、install、必要な環境変数の名前、起動commandを追加します。

成果物の説明軸は成果物で評価されるポイント、重要な変更は成果物の改善履歴を参照してください。

まとめ

READMEは、成果物の説明書です。目的、使い方、技術選定、工夫点を書くと、ポートフォリオとして伝わりやすくなります。

×

PR

×

PR