はじめに
前回書いた【Github】の Readme を修正した話では触れなかった項目に関して
自分なりに噛み砕いたことをアウトプットしました。
ReadMe の項目という正解のない話なので参考程度に読んでもらえる嬉しいです。
また、浅学なので補足や修正あれば教えていただけると幸いです。
テンプレート
必要なものだけ抜き取る形で使う
主に自分が使うために列挙
ここ以降は駄文です
## バッジ
## 画像や動画
## タイトル
## 画像や動画
## 説明
## 経緯
## デモ
## パッケージ
## 要件
## 使い方
## 今後やりたいこと
## 現状の問題
## 備考
## 貢献してください
## 製作者
## 協力者
## 参考ソース
## ライセンス
## スペシャルサンクス
以下 各項目の自己解釈
リポジトリ
リポジトリには色々なもの（資料集・作品・ライブラリなどなど）があるけど、
個別に分けれるほど知らないのでここではリポジトリで統一します
コスト
そのリポジトリのボリューム（コードの量だったり、載せてある資料の数だったり）。
ここではそれを軽い（少ない）・重い（多い）といった意味で使用しています
バッジ
↑こういうやつ
これを最初に表示することで見に来た人に、
このリポジトリが合っているかどうかがわかるようにするためのもの・・・らしい
調べてみたけどよく分からず。ただ、このバッジを貼ってるところはよく見るので記載しました。
タイトル
主にリポジトリの名前であることが多い
機能そのものを名前にしていることもある
稀に、〜して下さいと言った要望
もう更新していませんと言った宣言などもある
画像や動画
ReadMeで最初に目に入るコンテンツと思う
用意することができるなら必ず入れた方がいいんじゃないかと
使ったパッケージ(firebaseとか)をアイコンにして並べたりもする
説明
リポジトリの説明
ただ、ここで使い方を書いてることもある
コストの軽いリポジトリならここで使い方を説明してもいいと思う
説明の項目を抜いて使い方の項目だけ用意するのもいいと思う
経緯
リポジトリを作ったきっかけ
デモ
実際に動かしている映像だったり実際に動かせる URL を載せてたりする
つまり`画像や動画`と同じ役割のこともある
パッケージ
仕様技術を載せるところ
要件と混同されがち
『これがないと動きませんよ』とかあるのであれば、要件としたほうがいいのかもしれない
パッケージと要件を別々に書いてるリポジトリもあったと思う
リスト形式で書かれてることもある
要件
パッケージで説明したようにこれが無いとこのリポジトリは動かないよって記載するところ
条件と言ってもいい、パッケージか要件どちらかあればいいと思う
ただ、そもそもどれも無いと動かなくない？そう考えると
パッケージ（暗黙でこれがいるから）ってしてるところと
必要ですよとちゃんと要件って明記してくれてるだけの差なのかもしれない
リスト形式で書かれてることもある
使い方
説明と混同されがち
コストの重いリポジトリであれば説明と使い方は分けた方が可読性が上がる
コストの軽いものであれば説明か使い方どちらか一つでいいと思う
このリポジトリのインストールの仕方とか
起動の仕方とか書いてる
git clone 〜〜 と書いてるところをよく見る
今後やりたいこと
今後実装予定の機能やこうしていきたいといったことが書いてるところ
リスト形式で書かれてることもある
現状の問題
今直面している問題
自分が見つけたのでは資金繰りが厳しく更新できないといった内容や
もう更新停止していますといった内容があった
後は、他にもっといいライブラリ出たから辞めますとかもあるかもしれない
使ってる人が多いリポジトリであればあると親切かと
備考
追記で書きたいこと
なんでも書いていいところ
こだわりとかを Features として書いてるところもあり
貢献してください
プルリクしてねってところを複数見かけた
もっとこのリポジトリをよく出来る様に、こんな風にコード書き換えましたよ！とか送ってねって意味かと
後は問題があったら報告お願いしますとか
資金調達とかもあるのかもしれない
製作者
作った人
複数人で作ったリポジトリで使う？
協力者としてるところもある様子
協力者
リポジトリを作る上で協力してくれた人達のことを書く
その人達の github があればそこにリンクを貼ってる様子
`スペシャルサンクス`は github にいない人達だったり会社だったり団体だったりと広い意味で使われてる様子
参考ソース
このリポジトリを作る上で参考になった資料を載せるところ
リンクを貼ってあることが多い
資料の名前だったりもする
ライセンス
これが無いと github のデフォルトのライセンス扱いになる
fork と clone はしていいけど他はだめだよみたいな感じだったかと（あまり自信ないです）
基本的には載せた方が親切
詳しいところは調べてください
MIT ライセンスが多い印象
スペシャルサンクス
`協力者`の欄で説明したことと同じ
以上（他にもあるとは思いますが自分が調べたり浮かんだもので書いてます）
使われていた項目を一部羅列
日本語は訳だったり意図と思われるものを書いてます。
また、分け方に明確な基準はなく、恐らくこのカテゴリになるのかなといった形で分けています。
- 目次
- Table of contents
- タイトル
- Title
- 説明
- Description
- Features
- Instructions for Users
- Project Info
- Philosophy
- Performance
- What is it?
- Disclaimer （気をつけること 注意といった意味で使う）
- CAVEAT （気をつけること 注意といった意味で使う）
- 経緯
- Description
- Motivation
- デモ
- DEMO
- パッケージ
- Packages
- 要件
- Requirement
- Prerequisites
- 使い方
- Usage
- Using リポジトリの名前 (using sample みたいに使う)
- Example Usage
- Installation
- How to Build
- How to Install
- Setup Instructions
- Tutorials
- Basic Installation
- 今後やりたいこと
- Future features
- Blueprint（青図、完成図）
- 現状の問題
- issue
- CAVEAT
- Status（現在の状態という意味で）
- 備考
- Anything Else
- Note
- Other
- Extra Information
- Useful Information（お役立ち情報的な）
- 貢献してください
- Please contribute
- Contribute
- How to contribute
- Contributing
- Project Backers
- 製作者
- Author
- 協力者
- Contributors
- 参考ソース
- More resources
- References
- ライセンス
- License
- スペシャルサンクス
- Special Thanks
- その他
- Scope （対象者を絞る場合に使う）
最後に
プログラミングを勉強し出してそろそろ半年
ReadMe を書くときにいつもどう書いたらいいのか迷うので今後のために記事にしました
人の数だけ書き方も変わるものなので
ReadMe を作成する際に少しでも参考になっていれば幸いです。