READMEの活用

最終更新: 2022年01月14日

開発環境をディズニーランドにたとえるとREADMEは入り口に置かれている園内ガイド冊子です。どこで何をすべきか、どのように振舞うべきかがマニュアル的に書かれているものです。

READMEでカバーする内容一例

  • 環境構築の方法(npm iなど)
  • 環境構築における注意点
  • コーディングスタイルガイド(あれば)
  • デザインスタイルガイド(マテリアルデザインなど)
  • マークアップ記法(BEMなど)
  • コミットメッセージルール(あれば)
  • 依存する外部SaaS(Stripe、Algoliaなど)
  • デプロイフロー(どうやってデプロイするのか?)
  • 開発環境の存在と切り分け方(あれば)
  • 本番URL
  • 各種権限(Firebaseの管理権限は付与されるか?など)
  • タスク管理の方法
  • その他注意点

最終的な確認方法としては

「何も知らない状態の新人が明日からあなたのプロジェクトに参加する際、READMEを見れば直ちに迷わず開発に参加できる状態になっているか?」

を自問することです。

ダメな例

情報が散在している

XXXはバックログ(タスク管理ツールのこと)、XXXはWiki、XXXはスプレッドシート、XXXはGoogleDriveといった形で開発に関する情報が散在しているは避けましょう。新メンバーが開発環境を理解するためのキャッチアップコストと情報のメンテナンスコストが高くなります。

端折られすぎている

最低限の環境構築方法しか書かれていない場合、新人が入るたびに

  • 〜はどこにありますか?
  • CSSの記述にルールはありますか?

などの確認を受けることになります。そういった質問がこないようにREADMEに開発に必要な情報を詰め込んでおきましょう。

バッジを表示する

OSSリポジトリではしばしばバッジを目にします。昨今のサービスはほとんどの場合CIで自動デプロイや自動テストを行っているので、それらのステータスをバッジとして置いておくと良いでしょう。

見たことあるやつ

バッジ表示用のタグはCIサービスごとに発行されているので確認してみましょう。GitHub Actionsの場合こちらにあります。