はじめに

思わず使いたくなるWebアプリには、もれなくキレイなREADMEが書かれています。
そこで今回は、Webアプリが映えるキレイなREADMEの書き方についてまとめます。

こちらがテンプレートなので良ければ使ってみてください。

章	タイトル	備考
1	ヘッダー画像について
2	サービス概要
3	サービスを作成した背景
4	使い方
5	メイン機能
6	使用技術
7	インフラ構成
8	ER図
9	工夫点
10	今後の展望・追加機能について

前提

scaffoldを用いたRailsアプリを基にREADMEを作っていきます。
この時点で最高にかっこいいですね。

ヘッダー画像について

まずはCanvaを作ってカッコいいヘッダーを作りましょう。
サイズは1200*630がオススメです。

サービス概要

サービス名

The Posts
本当はここにサービスURLを入れます。

概要

思い入れ0投稿アプリ

サービスを作成した背景

サービスを作成した経緯を書くと、Why Youの部分が解消され、興味を持ってもらえるきっかけになります。

例: 記事を書くために作りました、特に思い入れはありません。

使い方

使い方を簡単に書いておくと、読み手がストレスなくどんなアプリなのかがわかってもらえます。
GIFを使って概要を視覚化しましょう。

シェア部分のマークダウンのGIFでURLをコピーできるので、テンプレートの部分を張り替えてもらえれば、簡単にできます。

例: scaffoldを使って簡単に投稿ができるアプリです。デプロイしていないので皆さんは使えません。

メイン機能

キレイにREADMEを書いている人は、もれなくテーブルとGIFを活用して、機能の説明をしています。これだけでかなり差別化できます。
Gyazoを使って、GIFを撮影しましょう。

さきほどと同じく、シェア部分のマークダウンのGIFでURLをコピーできるので、テンプレートの部分を張り替えてもらえれば、簡単にできます。

投稿機能	削除機能

投稿できます！すごい！	削除もできます！すごすぎる！

使用技術

使用技術についてまとめましょう。リスト形式もありますが、個人的にはテーブルでまとめる方がスッキリしていて好みです。

カテゴリ	技術
フロントエンド	CSS
バックエンド	Ruby 3.2.2 Rails 7.0.8
データベース	SQLite
認証
環境構築
CI/CD
インフラ
API
その他

選定理由

選定理由について書きましょう。こだわりが出る部分なので、厚みを持たせて書くと良さそうです。

例: 実装スピードを考慮しました。こだわりがないので、scaffoldを用いて、3分で完成させました。

インフラ構成

今回はそんなものはありません。他の有識者の記事を参考にしましょう。

ツールとして、Draw.io、Figmaあたりがよく使われている印象です。

ER図

テーブルが一個しかないので、全く映えないので書けません。こちらも他の有識者の記事を参考にしましょう。

ツールとして、Draw.io、PlanetUML、dbdiagramあたりが良さそうです。

画面遷移図

ここも載せられるならやっておいた方がいいです。
Figmaを使って書くのが主流です。

工夫点

工夫点を書きましょう。ここもこだわりを出しやすいので、厚みをもたせましょう。

1.工夫

h1にTheを追記することによってイケてるアプリにしました。

変更前

<p style="color: green"><%= notice %></p>

<h1>Posts</h1>

<div id="posts">
  <% @posts.each do |post| %>
    <%= render post %>
    <p>
      <%= link_to "Show this post", post %>
    </p>
  <% end %>
</div>

<%= link_to "New post", new_post_path %>

変更後

<p style="color: green"><%= notice %></p>

<h1>The Posts</h1>

<div id="posts">
  <% @posts.each do |post| %>
    <%= render post %>
    <p>
      <%= link_to "Show this post", post %>
    </p>
  <% end %>
</div>

<%= link_to "New post", new_post_path %>

今後の展望・追加機能について

今後について書くことで、よりユーザの興味関心を持ってもらいやすくなります。
例: 現状、The Postsなので、The Perfect PostsにすることでUI/UXを向上させたいです。

おわりに

READMEを充実させて、映えるアプリを作っていきましょう！
最後まで読んでいただきありがとうございました！

章	タイトル	備考
1	ヘッダー画像について
2	サービス概要
3	サービスを作成した背景
4	使い方
5	メイン機能
6	使用技術
7	インフラ構成
8	ER図
9	工夫点
10	今後の展望・追加機能について