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