読みたくなるREADMEを書くためのコツ

はじめに

こんにちは！ご訪問いただき、ありがとうございます！

僕は現在、エンジニアとしての就職を目指しながら、インボイス制度に対応した請求書を、Web上で作成・発行できるサービスの開発をしています。

その開発を進めていく中で、読んでもらえるREADMEを作成したいという想いから、世の中の開発者がどのようにREADMEを作成しているのかを、GitHubで調べて分析をしました。

本記事では、たくさんのREADMEを見て学んだ、読みたくなるREADMEを書くためのコツを、実際に僕が作成したREADMEを例にしてご紹介します。

前提

今回ご紹介する内容は、未経験でエンジニア就活をする際に、採用担当の方が読みたくなるようなREADMEを作成することを目的とした内容となります。

また、実際に作成したREADMEを例にコツのご紹介していますが、時間の兼ね合いで、学んだコツを反映できていない部分も多々あります。

あくまで参考資料として、ご覧いただけましたら幸いです。

実際に作成したREADME

READMEの構成

読みやすいREADMEは、以下の構成がベースになっていることが多いです。

1. どのようなサービスなのかを表現するひとこと
2. サービスの雰囲気が伝わる画像
3. サービスのURL
4. サービスに関する記事のURL
5. サービスの概要
6. サービスを開発した背景
7. 画面や機能の説明
8. 主な使用技術
9. ER図
10. インフラ構成図
11. 今後の展望

読み手が知りたいことを知りたい順番で書く。
想定している読み手やサービスの特徴によって、項目の追加や削除、内容の厚さの調整をする。

導入部分

• サービス内容をぱっと見て理解できるように書く。
• サービス内容を表現するキャッチーなフレーズを書く。
• サービスの雰囲気や内容が伝わる画像を配置する。

サービスのURL

• 文章を読むよりもサービスを実際に使いたいと考える読み手もいるので、早い段階でURLを書く。
• サービスを利用してもらう前に伝えたいことがあれば併せて表記する。

サービスの概要・開発した背景

• 具体的なサービスの内容を書く。
• サービスのターゲットの特徴を書く。
• サービスが解決する課題を書く。
• 開発への想いや動機を書く。
• サービスの価値が何かを書く。
• 工夫したことや、こだわたことを書く。
• 苦労したことを書く。

画面や機能の説明

• テーブルタグを使用してレイアウトを整える。
• 機能と併せて画像を配置することで、より読みやすくなる。
• カラム数は画面や機能に応じて変更する。
• 画像が大きいとその分スクロールする手間が生まれる。
• 画像が小さいと画面の内容がわからない。
• 機能一覧を箇条書きで表現した場合、機能数が多いと読み手のストレスとなるので注意が必要。

使用技術

• サービスで使用した技術を書く。
• カテゴリごとに書く。
• テーブルタグを使用するかリスト形式で書く。
• 特に伝えたい技術を中心に書く。
• 使用している技術のバージョンを書く。

ER図・インフラ構成図

• デザインの基本である近接・整列・反復・対比を意識する。
• 四角の四隅の処理（直角・角丸）を意識する。
• 余白を意識する。

今後の展望

• 追加したい機能を書く。
• 将来どのようにサービスを展開するのかを書く。
• 将来的に改善をしたいことを書く。

全体を通して

ここまでブロックごとにコツを書いてきましたが、最後に全体を通してのコツをご紹介します。

• 画像や絵文字を使用して、読み手を惹きつける工夫をする。
• 異なる種類の絵文字を多用すると、かえってストレスを感じる文章になるため注意が必要。
• ひとつの文章のまとまりを、より短く、より分かりやすくする工夫をする。
• 各ブロックごとに<br>タグを使用してブロック間の余白をつくることで、レイアウトがより綺麗になる。
• より少ないアクション(目線の移動・スクロール・クリックなど)とエネルギー（読み手が理解するためのエネルギー）で、より多くのことを読み手が理解できる工夫をする。
• 素敵なREADMEを沢山みて学び、自分のREADMEの作成に活かす。

終わりに

今回は、沢山のREADMEをみて学んだ、読みたくなるREADMEを作成するコツをご紹介しました。
READMEの作成に困った時は、またいつでも、こちらにいらしてください。
ここまでご覧いただき、ありがとうございました。

例として使用したREADMEのURL

https://github.com/ren-ichinose/Accel

参考にさせていただいたREADMEのURL

https://github.com/shiramizu-junya/personal_history

https://github.com/terakura-aina/Date_me

https://github.com/da-yoshi-k/huddle-guide

https://github.com/ryota1116/zero_calorie

https://github.com/Jun-Araki/sengokubusyou

https://github.com/Riri0000/min-kakeibo

https://github.com/palette3995/bandapp