はじめに
GitHubでレポジトリを作成すると最初に作成されるREADME.md。
デフォルトのまま放置していたりしませんか？
README.mdはレポジトリの顔です。
ここを整えておくことで、レポジトリのクオリティをぐっと上げることができます。
しかし、README.mdに何を書いたらいいのか、わからないという人も多いと思います。
この記事ではおすすめの構成をまとめます。
README.mdの読者はだれか？
まず、誰に向けてREADME.mdを書くのかというところから考えることから始めましょう。
README.mdの読者は大きく分けてユーザと開発者の２種類います。そのレポジトリを閲覧するひとはユーザが多いのか、開発者が多いのかを想定してどちらをメインで書くか決めると良いでしょう。
README.mdは英語で書くべき？
有名OSSはすべて英語でREADME.mdが書かれているため、当然英語で書くものという認識があるかもしれません。しかし、メインの閲覧者が日本語識者であるならば、README.mdも日本語で書くべきです。また英語で書くことにこだわって中身が薄くなるのでは本末転倒です。近年翻訳技術は飛躍的に向上しているので自分の得意な言語で書いてから翻訳するというのも一つの手でしょう。
ユーザが知りたいこと
Getting Started (入門ガイド)
ユーザがツールを試してみるために必要な手順です。基本的な構成は以下のようになります。
- インストール手順
- ツールの基本的な使い方
これが書いていないとユーザはツールを使ってくれません。必ず書くようにしましょう。
またGetting Startedの長さがそのツールを使うハードルの高さを表します。
理想的にはインストールはワンライナーで完了し、使用手順も数ステップで完了するものが望ましいです。
書いてみて手順が長すぎるようなら、短くできないか検討してみましょう。
インストール手順を短くするのが難しい場合は、Playground用のWebサービスを用意したり、Docker Imageを作成するのも一つの手です。
マニュアル
README.mdに利用マニュアルやAPIリファレンスへのリンクがあるとユーザは非常に助かります。
これらのドキュメントにはチュートリアルとリファレンスの２種類があることを意識して、それぞれをバランス良く整備するとよいです。
チュートリアル
ツールの典型的なユースケースを記述します。なるべく丁寧にスクリーンショット付きでStep By Stepに記述することを心がけましょう。Read the Docs等で書くのがおすすめです。
リファレンス
ツールの仕様を詳細かつ網羅的に記述します。
作成しているものがライブラリの場合、大抵のプログラミング言語にはリファレンス自動生成機能がついているので、ドキュメンテーションコメントでソースコードに記載したものからツールで自動生成しましょう。
ツールの場合はRead the Docs等を用いますが、リファレンスとソースとの整合性を担保するためになるべく機械的に生成できるようにしておくべきです。
リリースノート
リリースノートを書いておくとユーザがツールをバージョンアップする時に役立ちます。
ベータ版等プレリリースのバージョンでは必要ありませんが、バージョン1.0以降のリリースでは必ず書くようにしましょう。過去に遡って調べて書くのは大変なので、リリースごとに必ず追記するようにしましょう。
リリースノートもREADME.mdに直接書くよりも、CHANGELOG.mdやGitHub Releases等に書き、そのリンクを記載するべきです。
リリースノートの書き方は以下のサイトの記法に従うのがおすすめです。
リリースノートを書く際に、新しくリリースした機能について詳しくアピールしたくなる気持ちになりますが、リリースノートはバージョンアップのための文書であり、実はここを読む人はそれらにはあまり興味はありません。
新規機能は別途リリースハイライトやブログ等でアピールしましょう。
リリースノートでは以下の２点がわかるようにしましょう。
- どのバージョンまで上げれば良いか？
- 脆弱性が修正されたのはどのバージョンか？
- サポートしているランタイムやミドルウェアに変更はあるか？
- バージョンアップ時にどのような対応が必要か？
- 破壊的変更があるか？（セマンティックバージョニングに従いましょう）
- 非推奨となった機能の代替は何か？
サポート窓口・バグ報告方法
README.mdにはサポート窓口を明記しておくことで、ユーザからのフィードバックを集めることができます。サポートとバグ管理は似て非なるものです。どちらもIssuesで管理することもできますが、サポートはメーリングリストやSlack、Discordを用いる方法もあります。また、よくある問い合わせについてはトラブルシューティングのドキュメントを用意しておくのも良いでしょう。
どのような方法でも良いのですが、サポート窓口を明記しておくことが重要です。
また、利用者は問い合わせる前に問い合わせ方法をちゃんと読んでその作法に従うようにしましょう。
開発者が知りたいこと
開発者向けのドキュメントは CONTRIBUTING.mdに書くこともできますが、READMEに記載するケースもよくあります。CONTRIBUTING.mdに書く際にもREADMEから辿れるようにリンクを張りましょう。
開発環境のセットアップガイド
開発者向けのGetting Startedです。
- 必要なツールのインストール方法
- ビルド方法
- （必要に応じて）認証情報の取得先と設定方法
- ローカルでの実行方法
をまとめます。こちらもなるべく短いステップで開発環境を構築できるようにしましょう。
devcontainer.jsonやクラウド開発環境を用意してそこで開発するというスタイルももちろんありですが、どのようなツールをインストールする必要があるかを書いておくと、環境構築のブラックボックス化を防ぐことができます。
テスト方法
開発者向けのドキュメントで最も重要なのがテスト方法です。最低限、単体テストの実行方法とスモークテストの実行方法は必ず書くようにしましょう。これらがあれば開発者は自身の環境構築トラブル時に問題の切り分けを行うことができます。
テスト環境の接続情報や認証情報はレポジトリで直接管理することはできませんが、入手先や取得場所を書いておくと良いでしょう。
デプロイ・リリース方法
ローカル開発後に実施する作業手順を記載します。例えば、開発しているものがサーバならば、ステージング環境にデプロイして結合テストを実施する方法を記載します。また、開発しているものがクライアントプログラムの場合はパッケージングしてRelease Candidatesを作成して結合テストを実施する方法を記載します。
これらの手順をちゃんとドキュメント化しておかないとよく属人化や作業漏れが発生します。CI/CDで自動化されている場合も、どこで何が実施されていてどこから結果を確認できるか書いておくと良いでしょう。
設計資料・コーディング規約等のリンク
サーバの構成図やソースのパッケージ構造など全体を俯瞰した資料(ARCHITECTURE.md)を作成しておくと開発者がデバッグする際や修正方法を考える際に役立ちます。またコーディング規約はソースコードの品質を担保するのに役立ちます。
開発プロセス
最後にチケットの起票方法、ブランチ戦略、PRの作成方法など、コード以外の開発ルールを記載しておきましょう。
開発プロセスを整えておくと、そのレポジトリの「治安」が良くなります。チケットの起票ルールが揃っていないと開発ロードマップやリリースノートを作成するのに苦労しますし、ブランチ戦略が整っていないと開発ブランチが不安定になり開発スピードが低下します。またPRにもルールをつけておかないとテストのないコードが増えてコードの品質が低下したり、マニュアルが陳腐化したりします。
README.mdをかっこよくするために
ここまでREADME.mdの中身を充実させる方法を紹介してきましたが、やはり見た目も大事です。
README.mdの見た目をかっこよくすることでレポジトリ自体もイケているように見えます。
ロゴを作成する
プロジェクトのロゴをREADMEに配置することでREADME.mdがグッとかっこよくよくなります。
ロゴがあることでそのレポジトリを認識してもらいやすくなりますし、愛着も湧いてきます。
最初はシンプルなもので良いですが、ロゴを決めておくと良いでしょう。
バッジを貼る
有名OSSのREADMEにはbuild: passing, npm: 2.7.3 みたいなバッジがいっぱいついています。
ソースを見ればわかりますが、これはただの画像リンクで、レポジトリの状態に応じて画像を動的に生成するサービスを利用しています。パブリックレポジトリならばshields.io等を用いるとかっこよくできます。
プライベートレポジトリの場合はこのサービスは使えませんが、GitHub自体がワークフローの成否バッチを生成してくれるので簡単なバッジならばこれで十分です。
まとめ
この記事ではREADME.mdに記載すべき内容を紹介しました。
README.mdを充実させることでレポジトリを利用しやすく、開発しやすくすることができます。
コードを書くのも大切ですが、時には自分のレポジトリのREADME.mdを改善してみてください。