READMEの書き方
Sinatraのメモアプリも残すはREADMEの作成のみです。 読みやすいREADMEの書き方を調べてみました。
結論
- 先輩の方々が公開しているテンプレートの内容をきちんと理解して活用する。
- ユーザー目線で考えて分かり易く書く。
僕が考える良いREADMEとは
- READMEを読んだだけで詳細、使い方が理解できる。
- 画像、表を使って視覚的に理解しやすい。
- READMEがそのまま要件定義になっている。
参考にしたいテンプレートの詳細
こちらの記事を参考にしました。
# Product_Name ## Description ***DEMO:***  ## Features ## Requirement ## Usage ## Installation ## Author ## License
Product_Name
- プロダクト名と概要。
- 概要は一文で説明できると良い。
- 対象リポジトリのDescriptionと同一が良さそう。
Description
- 説明。概要で説明しきれなかった細かい部分を説明。
- メイン機能の説明が良さそう。
- 単体画像よりもアニメーション画像の方がユーザーが使い方をイメージしやすい。
Features
- 特徴。
- 独自機能や強みを記載する。
- 多すぎる場合は別ページか
--help等を参照するように促す。
Requirement
- 必要条件。
- 動作に必要な環境、ツール等を記載する。
Usage
- 使用方法。
- 画像を使って操作のイメージし易さを重視する。
Installation
- インストール方法。
- セットアップから起動方法まで詳細を記載する。
- コマンドラインを順にコピペするだけで動作するように分かり易さを重視する。
Author
- 作者情報。
- Twitterアカウント等の連絡しやすい情報を記載する。
License
- ライセンス情報。
- ライセンス周りは良く分かっていないので割愛。
ユーザー目線でREADMEを書く
概要やデモを見て使うか捨てるかを決めるのに、それが README の後ろに埋もれていて、最初の方に Installation や Usage が来るのは不親切な UI です。
参照: わかりやすい README 駆動開発 - Qiita
ユーザー目線で使い易さ、読み易さを考えられており是非考え方を見習いたいと思いました。 コードを書くことにも通じる大事な考え方だと思うので意識していきたいです。
README駆動開発
README ありきの開発スタイルのことで、簡単に言うと「コード書く前に README 書く」ってことです。
今の自分はまだプロダクトを作ることは少ないけれど将来的に取り入れたい考え方だなと思った。
- RDD(Readme Driven Development)
- 要件定義に繋がる
- 開発のモチベーションを維持しやすそう
まとめ
READMEは思っていたより奥が深くて良い考えを知る良い機会になった。 良い影響を与えるようなプロダクトを作れるようなエンジニアになりたいと改めて思いました。
