by shigemk2

当面は技術的なことしか書かない

memo READMEに何を書く? #kbkz_tech

ツッコミがあったらください

個人的にやっていること

  • ライブラリがあったら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がどんどん長くなる
  • より詳細な話