READMEに何を書くべきか問題
リポジトリの顔とも言うべきREADMEに何を書くべきかは多くの方が議論されていると思いますが、ここではリポジトリのソースコードを利用して開発を始める時の手順（セットアップ）の記述に関して、自身の体験など踏まえて意見を整理しておきます。
READMEは誰が見るの？
リポジトリの作者や以前からのコミッターはそのリポジトリの内容に精通しているので、正直READMEなんて見なくても問題ないです。問題なのは初めてリポジトリを見に来た人たちです。ネットの大海原の中から奇跡的にこのリポジトリに辿り着いた通行人たち。リポジトリの目的や内容・特徴を簡潔に説明し、彼らに少しでも興味を持ってもらうための手段がREADMEと言えます。ですから、 READMEはリポジトリ初見の目線が大事です。 製作者のメモ書きみたいな暗号文を記載されても困ります。もっとも 数週間もすれば過去の自分はもはや他人です。 他人のメモ書きなんぞ解読不能です。
セットアップ方法が分からん
社会人として働く経験から気付かされました。自主開発中心の学生時代とは異なり、他者が作成したリポジトリを利用・コミッターとして参加する機会が増えたため、そのたびに開発環境を新しく用意します。困ったことにリポジトリによってはセットアップ方法の説明が不十分もしくは存在せず、経験者に質問して対応してもらうケースが多々ありました。正直、最初はREADME以外何を見ればいいか分からんし、最低限のセットアップ方法は記載して欲しい。まぁ、業務の場合は開発に必要な文書をREADME以外の方法・サービスで管理している場合もあり、READMEにまとめろ、とは一概に言えなさそうです。
ただし、自主開発などは言い訳できないので、 README読んでも分からん、となったら誰も見向きもしてくれないです。 かつての自分という他人が遺したリポジトリを修正しようと発掘しても、セットアップ方法が分からず開発が始まらん、とイライラします。リポジトリに対して最も精力的なはずの製作者ですらその有様なのですから、通りがかりの他人なら尚更です。イライラする前に理解を放棄して忘却の彼方です。
これ書いて欲しかった集
他者のリポジトリに対して、もそうですが過去の自分に対する反省としても経験を遺しておきます。
バージョン・依存ライブラリ
特にpythonはライブラリも含めバージョン管理が面倒なのでConda環境がほぼ必須。Conda環境の作成から案内してくれ。importエラーのたびに必要なライブラリを探してpip叩くのはもう嫌だ。requirements.txtにまとめて欲しい。
他のリポジトリに依存する場合
いや知らんがな。そっちもローカルにcloneする必要あるなら、最初にそう言ってくれ。
認証情報の用意
リモートリポジトリにpushしたくない情報は.gitignoreで除外することは多いが、開発に必要な情報であることに変わり無い。どこから認証情報を取得して、どのファイル・何の環境変数に書き出すのか指示してくれ。
外部サービスに依存する場合
開発するアプリがバックエンドを利用する場合など。デバッグやステージング・プロダクト環境などに応じて別々のエンドポイントだったり、認証情報が違っていたりする。書いてくれ。
Build方法
開発プラットフォームにスタンダードな方法が明白ならいい。例えばとりあえずnpm run buildと叩けば行ける。そうでないなら、どのスクリプト叩けばいいの？ Build時の設定値はどうする？書いてくれ。
挙げるとキリがないのでここまで。今後、自分が書く時には気をつけようと思います。