📑
読みたくなるREADMEを書くためのコツ
はじめに
こんにちは！ご訪問いただき、ありがとうございます！
僕は現在、エンジニアとしての就職を目指しながら、インボイス制度に対応した請求書を、Web上で作成・発行できるサービスの開発をしています。
その開発を進めていく中で、読んでもらえるREADMEを作成したいという想いから、世の中の開発者がどのようにREADMEを作成しているのかを、GitHubで調べて分析をしました。
本記事では、たくさんのREADMEを見て学んだ、読みたくなるREADMEを書くためのコツを、実際に僕が作成したREADMEを例にしてご紹介します。
前提
今回ご紹介する内容は、未経験でエンジニア就活をする際に、採用担当の方が読みたくなるようなREADMEを作成することを目的とした内容となります。
また、実際に作成したREADMEを例にコツのご紹介していますが、時間の兼ね合いで、学んだコツを反映できていない部分も多々あります。
あくまで参考資料として、ご覧いただけましたら幸いです。
実際に作成したREADME
READMEの構成
読みやすいREADMEは、以下の構成がベースになっていることが多いです。
- どのようなサービスなのかを表現するひとこと
- サービスの雰囲気が伝わる画像
- サービスのURL
- サービスに関する記事のURL
- サービスの概要
- サービスを開発した背景
- 画面や機能の説明
- 主な使用技術
- ER図
- インフラ構成図
- 今後の展望
読み手が知りたいことを知りたい順番で書く。
想定している読み手やサービスの特徴によって、項目の追加や削除、内容の厚さの調整をする。
導入部分
- サービス内容をぱっと見て理解できるように書く。
- サービス内容を表現するキャッチーなフレーズを書く。
- サービスの雰囲気や内容が伝わる画像を配置する。
サービスのURL
- 文章を読むよりもサービスを実際に使いたいと考える読み手もいるので、早い段階でURLを書く。
- サービスを利用してもらう前に伝えたいことがあれば併せて表記する。
サービスの概要・開発した背景
- 具体的なサービスの内容を書く。
- サービスのターゲットの特徴を書く。
- サービスが解決する課題を書く。
- 開発への想いや動機を書く。
- サービスの価値が何かを書く。
- 工夫したことや、こだわたことを書く。
- 苦労したことを書く。
画面や機能の説明
- テーブルタグを使用してレイアウトを整える。
- 機能と併せて画像を配置することで、より読みやすくなる。
- カラム数は画面や機能に応じて変更する。
- 画像が大きいとその分スクロールする手間が生まれる。
- 画像が小さいと画面の内容がわからない。
- 機能一覧を箇条書きで表現した場合、機能数が多いと読み手のストレスとなるので注意が必要。
使用技術
- サービスで使用した技術を書く。
- カテゴリごとに書く。
- テーブルタグを使用するかリスト形式で書く。
- 特に伝えたい技術を中心に書く。
- 使用している技術のバージョンを書く。
ER図・インフラ構成図
- デザインの基本である近接・整列・反復・対比を意識する。
- 四角の四隅の処理（直角・角丸）を意識する。
- 余白を意識する。
今後の展望
- 追加したい機能を書く。
- 将来どのようにサービスを展開するのかを書く。
- 将来的に改善をしたいことを書く。
全体を通して
ここまでブロックごとにコツを書いてきましたが、最後に全体を通してのコツをご紹介します。
- 画像や絵文字を使用して、読み手を惹きつける工夫をする。
- 異なる種類の絵文字を多用すると、かえってストレスを感じる文章になるため注意が必要。
- ひとつの文章のまとまりを、より短く、より分かりやすくする工夫をする。
- 各ブロックごとに
<br>タグを使用してブロック間の余白をつくることで、レイアウトがより綺麗になる。 - より少ないアクション(目線の移動・スクロール・クリックなど)とエネルギー（読み手が理解するためのエネルギー）で、より多くのことを読み手が理解できる工夫をする。
- 素敵なREADMEを沢山みて学び、自分のREADMEの作成に活かす。
終わりに
今回は、沢山のREADMEをみて学んだ、読みたくなるREADMEを作成するコツをご紹介しました。
READMEの作成に困った時は、またいつでも、こちらにいらしてください。
ここまでご覧いただき、ありがとうございました。
例として使用したREADMEのURL
参考にさせていただいたREADMEのURL
Discussion