はじめに
思わず使いたくなる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を充実させて、映えるアプリを作っていきましょう！
最後まで読んでいただきありがとうございました！