ツッコミがあったらください
個人的にやっていること
- ライブラリがあったらpublishする
- publishする
- READMEを書こうとする
- 何を書こうか…
方針
- 個人でしか使わない想定
- ライブラリ管理をpackage managerに任せたいという気持ち
- ドキュメントにコストをかけたくない
- どうせ自分しか使わないでしょう?
- とはいえ一ヶ月前の自分は他人なので
- ビルド方法を忘れていることが多いので、READMEがまっさらだとやる気がなくなってしまう
- 最低限書く必要のあるもの
- ライブラリ名
- 必須環境
- ビルド方法
- (publish方法)
- 他人にも使ってほしい場合
- まずpublish先を考える
- サービスによってはREADMEがそのまま利用されるケース(npm)
- 使うツールごとにREADMEに書くか別ファイルにしてリンクを貼るか決める
- 参考になるものを探す
- オレオレで書くのは心配
- 参考になりそうなものを調べる
- その言語で有名なライブラリなどのREADMEとか
- うまくいけばtypoも見つかるかも
- あるいはツールに任せる(scaffold)
- 日本語か英語か
- 広く使ってもらいたいなら英語
- めちゃくちゃでもいいので。ないよりはマシ。優しい人が書き直してくれるかも
- 英語心配なひとはコミュニティで英語つよそうな人に相談
READMEに必須そうなもの
- TL;DR(要約)
- インストール方法
- 公開している場所
- CIへのリンク(CI使っていないプロダクトは使うに値しない一派 ブラウザバック率がかわる)
- ChangeLogへのリンク
- API Referenceへのリンク
gh-pagesなど別の場所に配置する場合はこの場合ではない
READMEに入れるかどうか悩ましいもの
- LICENSEファイルがあるのにREADMEにライセンスいれるのどうなのか
- npmを使うときは入れてる(バッチとか)
別ファイルに分けるもの
- Change log
- READMEがどんどん長くなる
- より詳細な話