伝わるGitHub README.mdの書き方 ― 就活で「読まれる」ポートフォリオにするために

広告

就職・転職活動でGitHubのポートフォリオを公開する際、多くの人がコードの完成度にはこだわっても、README.mdへの意識が薄くなりがちです。

しかし採用担当者やエンジニアがリポジトリを開いたとき、最初に(そして場合によっては唯一)目を通すのがREADME.mdです。どれだけ良いコードを書いていても、README.mdが不十分だと「中身を見てもらう前に離脱される」ということが実際に起こります。

この記事では、就活・転職活動で使えるREADME.mdの書き方を、テンプレートと合わせて解説します。

README.mdに何を求められているか

READMEの役割は一言でいうと「初対面の人に、3分でプロジェクトを理解してもらう」ことです。採用担当者は次のような疑問を持ちながら読んでいます。

  • 何を作ったのか(概要)
  • なぜ作ったのか(動機・課題意識)
  • どうやって動かせるのか(セットアップ手順)
  • 技術的にどんな工夫をしたのか(学びや苦労した点)

この4点に答えられていれば、README.mdとしては及第点です。

README.mdはどこに、どうやって作るのか

「README.mdを書きましょう」と言われても、そもそもどこに作るファイルなのか分からない、という人も多いはずです。まずはここから確認しておきましょう。

置き場所はリポジトリの一番上(ルート)

README.mdは、プロジェクトのフォルダ構成でいちばん外側の階層(ルートディレクトリ)に置きます。src フォルダの中や、特定の機能のフォルダの中ではありません。GitHubはこの場所にある README.md を自動的に見つけて、リポジトリのトップページに表示してくれます。

ファイル名は大文字の README に拡張子 .md(Markdown形式)を付けた README.mdが慣習です。すべて大文字にするのは「目立たせるため」の昔からの習わしで、実際は小文字でもGitHubは認識しますが、迷ったらREADME.mdの表記に合わせておけば間違いありません。

作り方①:GitHubの画面上で直接作る(一番簡単)

作ったばかりで中身が空のリポジトリを開くと、トップページに次のような案内ボックスが表示されます。

  • 本のアイコンと「Add a README」という見出し
  • 「Add a README with an overview of your project.」という説明文
  • 緑色の「Add a README」ボタン
GitHubの空リポジトリに表示されるAdd a READMEの案内ボックスと緑色のボタン

このボタンをクリックするだけで、ファイル名が最初から README.md になった状態でファイル作成画面が開きます。あとは本文欄にMarkdownで内容を書き、ページ下部の「Commit changes」ボタンで保存すれば完了です。ファイル名を自分で入力する必要すらない、一番迷いにくい方法です。

なお、すでに何かファイルが入っているリポジトリでは、この案内ボックスは表示されません。その場合は「Add file」ボタン→「Create new file」を選び、ファイル名の欄に自分で README.md と入力して作成します。この場合、ページ下部のコミット画面で「mainブランチに直接コミットする」か「新しいブランチを作成してPull Requestを作る」かを選ぶことになります(詳しくは後述)。

保存すると、そのままリポジトリのトップページにREADMEの内容が表示されます。

作り方②:自分のパソコン(ローカル)で作る

VS Codeなど、普段使っているエディタで作業しているプロジェクトに追加する場合は、ターミナルからファイルを作成してGitHubに反映(push)します。個人のリポジトリならこのままmainブランチで作業して問題ありませんが、チーム開発中のリポジトリであれば git checkout -b docs/add-readme のようにブランチを切ってから作業しましょう(詳しくは後述)。

cd リポジトリのフォルダ
type nul > README.md   ※Macの場合は touch README.md

ファイルができたら、VS CodeなどでREADME.mdを開いてMarkdownで内容を書き、保存したら次のコマンドでGitHubに反映します。

git add README.md
git commit -m "READMEを追加"
git push

pushが終わったら、GitHub上のリポジトリページを再読み込みして、内容が反映されているか確認しましょう。

チーム開発中のリポジトリでは、ブランチを切ってから作る

作り方①で紹介した、作ったばかりの空のリポジトリで「Add a README」ボタンを使う場合は、そもそも他に作業中のブランチが存在しないので、この話は気にしなくて大丈夫です。注意が必要なのは、①のうち「すでにファイルがあるリポジトリでAdd fileから作る」パターンと、②のローカルで作ってpushするパターンです。どちらも、すでに動いているチーム開発リポジトリに対して使う可能性がある手順だからです。

一方、すでにチームで開発が進んでいるリポジトリ(複数人がそれぞれのfeatureブランチで作業しているようなプロジェクト)にREADME.mdを追加・編集する場合は少し注意が必要です。GitHubの画面でファイルを編集すると、コミット時に「mainブランチに直接コミットする」か「新しいブランチを作成してPull Requestを作る」かを選ぶ画面が表示されます。

チームですでにブランチ運用のルールがある場合は、READMEだけ例外的にmainへ直接コミットしてしまうと、他のメンバーの変更とコンフリクトしたり、「ドキュメントだからいいや」で運用ルールが崩れ始めたりしがちです。チーム開発中は、READMEの変更もほかのコードと同じようにブランチを切ってPR経由でマージするようにしましょう。

場所と作り方を確認できたところで、次は実際に「何を書くか」を見ていきます。

基本構成

以下が就活ポートフォリオ向けの標準的な構成です。

# プロジェクト名

## 概要
このプロジェクトが何であるか、1〜2文で説明する

## デモ
![デモ画像またはGIF](path/to/demo.gif)

## 使用技術
- 言語: C#, JavaScript
- フレームワーク: Unity, React
- その他: Git, VS Code

## 機能一覧
- 機能A: 説明
- 機能B: 説明

## セットアップ方法
（コマンド例は下記参照）

## 工夫した点・学んだこと
このプロジェクトで直面した課題と、どう解決したかを書く

## 今後の課題
未実装の機能や改善したい点

## ライセンス
MIT License など

各セクションのポイント

概要は「誰が読んでも分かる言葉」で

技術用語を並べるのではなく、「何のためのアプリか」を平易な言葉で書きます。たとえば「MVVMパターンを採用したTodoアプリ」よりも先に、「タスクを期限順に管理できるTodoアプリです」という一文を置きましょう。

デモ画像・GIFは必ず入れる

文章だけのREADMEと、動いている様子が分かるGIFが1枚あるREADMEでは、読まれる確率が大きく変わります。ScreenToGifやKapなど無料ツールで数秒の操作動画を撮り、GIFに変換して貼るだけで印象が変わります。

「工夫した点・学んだこと」が一番読まれる

採用担当者が本当に知りたいのは機能一覧よりもここです。「なぜその実装方法を選んだか」「うまくいかなかった箇所をどう乗り越えたか」を具体的に書くと、思考のプロセスが伝わります。

例えば、次のような書き方です。

当初はコルーチンで非同期処理を実装していましたが、処理のネストが深くなり可読性が落ちたため、async/awaitに書き換えました。これによりエラーハンドリングも try-catch でまとめられ、コードの見通しが改善しました。

Markdown記法の実用テクニック

バッジを使う

使用技術を視覚的に示すバッジは、GitHubプロフィールでよく使われます。

![C#](https://img.shields.io/badge/C%23-239120?style=flat&logo=c-sharp&logoColor=white)
![Unity](https://img.shields.io/badge/Unity-100000?style=flat&logo=unity&logoColor=white)

コードブロックには言語名を指定する

シンタックスハイライトが効くよう、コードブロックの先頭に言語名を書く習慣をつけましょう。

public class Player : MonoBehaviour
{
    // ...
}

Markdown上では次のように、コードの前後を3つのバッククォートで囲み、言語名を添えます。

```csharp
public class Player : MonoBehaviour
{
    // ...
}
```

セットアップ手順はコマンドで示す

動かし方は文章で説明するより、コピーしてそのまま使えるコマンドを載せたほうが親切です。

git clone https://github.com/ユーザー名/リポジトリ名.git
cd リポジトリ名

折りたたみでスクリーンショットをまとめる

複数枚の画像を貼ると縦に長くなりすぎる場合は、<details>タグで折りたためます。

<details>
<summary>スクリーンショット一覧</summary>

![画面1](img1.png)
![画面2](img2.png)

</details>

よくある失敗例

  • 「TODO: あとで書く」のまま放置 ― 面接直前に見返して慌てるパターンです。区切りの良いタイミングで都度更新しましょう。
  • セットアップ手順が動作確認されていない ― 別のPCやクリーンな環境で一度試すと、抜けている手順(必要なパッケージのインストールなど)に気づけます。
  • 機能一覧だけで終わっている ― 何を作ったかは分かっても、なぜ・どう作ったかが伝わらず差別化になりません。

おわりに

README.mdは「コードの説明書」ではなく「あなたの思考プロセスを伝えるプレゼン資料」だと捉えると、書くべき内容が見えてきます。完成度の高いコードと、それを正しく伝えるREADME.mdの両方が揃って、初めてポートフォリオとして機能します。

次回は、実際にゼロからREADME.mdを書き上げる過程を、就活生の個人プロジェクトを例に紹介する予定です。

訪問数 3 回, 今日の訪問数 3回

広告

Git

Posted by hidepon