READMEとは?
アプリケーションの利用者に最初に読んでほしい内容(免責など)をまとめたREADME.txtというファイルを、アプリケーションに同梱する慣習があります(ファイル名はREADMEだったりREADME.1stだったり、日本語ではじめにお読みください.txtだったり、色々ありましたが)。今ではMarkdownを利用し、ファイル名はREADME.mdとなっていることが多いです。
最初に読んでほしいということで、GitLabはこのREADMEの内容プロジェクトトップページに表示します。
プロジェクトトップページ
GitLabのプロジェクトにアクセスした人が初めて見るドキュメントですので、アプリケーションの概要や簡単な使い方の例、開発環境の構築方法やアプリケーションの実行方法などを記載します。
READMEが簡潔で読みやすく、十分な情報を含んでいると、アプリケーションを使おうと思っている利用者や、新しい開発メンバーにとってとても役立ちます。
開発リーダーはプロジェクトに新しい開発メンバーを加えます。新しい開発メンバーはプロジェクトページにアクセスしREADMEを読みます。開発リーダーの助けなしに、READMEに記載されているプロジェクトのゴールを理解し、開発環境をセットアップし、仕様書や設計書を読み始めることができるでしょう。最初に割り当てられた簡単なイシューを開始し、プロジェクトへの貢献を始めることができます。
READMEには何を書く?
READMEはGitLabプロジェクトにアクセスして最初に表示されるドキュメントです。見る人によって欲しい情報は変わりますので、どういった人がアクセスに来るのかを想定するのが大事です。アプリケーションの利用者と開発側では大きく異なります。
利用者向け
利用者といっても、アプリケーションを探している人、使おうと思っている人、使っているけど要望がある人など様々です。次のような情報を書いておくとよいでしょう。
- アプリケーションの概要 - いろんなアプリケーションを試そうと思っている人は、短い時間でどういうアプリケーションかを知りたがります。文章はもちろんですが、スクリーンショットやGIFアニメーションも利用してわかりやすく紹介するとよいでしょう。。
- 動作環境 - 利用者はあなたのアプリケーションが自分の環境で動くのかどうかを気にします。対応OSやブラウザーなどが書かれているとよいでしょう。
- アプリケーションの使い始め方 - あなたのアプリケーションをいち早く使えるようにするために、インストール方法やアカウントの取得方法を紹介します。加えて、一番簡単な使い方もあるとよいでしょう。
- バグや要望の報告方法 - あなたのアプリケーションの利用者の中には、バグや要望の報告をしようとするありがたい人もいるでしょう。
なお、開発の初期段階や受託開発などはアプリケーションの利用者がプロジェクトページにアクセスすることはあまりありません。その場合、不要な情報は省略します。
開発側向け
開発側といっても、マネージャー・開発者・テスターなどなどいろんな立場の人がいます。すべてREADMEに書くととても長くなります。一番人が多いのは開発者ですので、開発者向けの情報を中心に書いていくことになります。
- 開発のゴール
- 顧客情報 - 受託開発ではお客様が誰かも重要な情報です。
- 開発体制 - 開発責任者・運用責任者などの各責任者程度はあるとよいでしょう。開発メンバーが困ったときに誰に質問するかがわかりやすくなります。
- 開発に必要なもの - 開発に利用するOS・統合開発環境・ライブラリ・フレームワーク・クラウドなどを書きます。新しく参加した開発メンバーのために用意しなければならない有償製品へのライセンスやクラウドアカウントの用意を忘れることがなくなるでしょう。
- 開発環境の構築方法と実行方法 - 新しく参加した開発メンバーが、助けなしに開発環境を構築し、アプリケーションの開発に入れるようにします。
- デバッグ方法や自動テストの方法など、最低限知ってほしいもの
- 仕様書・設計書・コーディング規約・アーキテクチャ図などのドキュメントへのリンク
- 参考になる書籍やウェブサイトへのリンク
長くならないように
READMEは長くなりがちです。長くなってしまうと、読むのを敬遠されたり読み飛ばされたりします。せっかく用意したのが無駄になります。
アプリケーションの概要や開発のゴールのような短くて重要な情報はREADMEにそのまま載せたほうがよいでしょう。
開発環境の構築方法や参考資料集・FAQなどは長くなりがちです。短いうちはREADMEに書いても構いませんが、長くなってきたら、別のファイルに移動し、READMEからリンクを貼りましょう。
わかりやすく
READMEを書いている本人はわかりやすく書いているつもりです。残念ながらただ書いただけではわかりやすくなりません。間違いもあるでしょう。READMEを特定の人にまかせるのではなく、みんなでいろいろ意見を出し合いながら整理し続けるのが大事です。
また、新しいメンバーが参加したときは改善のチャンスです。新しいメンバーに躓いたところ、わかりにくいところ、不足しているところを聞き出して修正しましょう!
定期的に見直す
時間が経つと、READMEの内容が現状と合わなくなってきます。利用する開発ツールやクラウドサービスの数は増えるでしょうし、開発ツールのバージョンや設定も変わるでしょう。これらを放置すると、チームの暗黙知が増えていきます。暗黙知ならまだ聞けばすみますが、最悪の場合、開発環境の設定方法をみんな忘れていて、構築できなくなってるなんてこともあります。
理想はその場で直すことです。しかし、修正を忘れることもよくあります。定期的に内容を見直してください。
READMEの仕様
READMEファイルのバリエーション
READMEはREADME.mdという名前のファイルを使うことが一般的ですが、index.mdとファイル名にindexを使うこともできますし、Markdown以外にもAsciiDoc (README.adoc)やreStructuredText (README.rst)などの他の形式を利用することもできます。詳しくは公式ドキュメントのREADME and index filesやSupported markup languagesをご覧ください。特に、AsciiDocやreStructuredTextはMarkdownに比べ表現力が豊富ですので、Markdownに不満がある方は試してみてはいかがでしょうか?
ディレクトリのREADME
READMEはリポジトリのルートディレクトリだけでなく、ディレクトリにも配置できます。GitLabのリポジトリブラウザーでディレクトリを表示するとREADMEの内容も合わせて表示されます。
ディレクトリのREADME
docs/index.mdファイルにドキュメントの目次を書くのはとてもよいアイデアです。サブシステムのディレクトリにサブシステムの概要が記載されたREADMEを配置すると、開発の助けになるでしょう。
図を埋め込む
GitLabのMarkdownはMermaidやPlantUMLを利用して図を埋め込むことができます。クラス図やシーケンス図などを埋め込んだ、よりわかりやすいドキュメントを書くことができます。
Mermaidを利用して図を埋め込んだ例
注: PlantUMLはGitLabの管理者が有効にしない限り利用できません。利用できるかはGitLabの管理者にお問い合わせください。なお、GitLab.comでは利用できます。
README以外の特別なドキュメント
README以外にもGitLabが特別扱いをするドキュメントファイルがいくつかあります。それらについても簡単に紹介します。
これらはプロジェクトトップページにリンクが表示されます。
プロジェクトトップページの各ドキュメントへのリンク
CONTRIBUTING
CONTRIBUTING.mdファイルはその名の通り、開発者向けの情報をまとめるためのものです。READMEに利用者向けと開発者向けの両方の情報を書くと長くなってしまいます。開発者向けの情報はCONTRIBUTINGに書き、READMEには「開発者はCONTRIBUTINGを読んでください」とリンクを書くことができます。
READMEのみにするか、READMEとCONTRIBUTINGの組み合わせのどちらにするかが悩みどころですが、掲載する情報が十分に短いときはREADMEのみというのが一般的のようです。
特に、開発の初期の頃は利用者がプロジェクトページにアクセスすることはありませんので、まずはREADMEのみで始め、利用者向けの情報も追加して長くなってきたら、開発者向けの情報はCONTRIBUTINGまたは他のファイルへ移動するのがよいでしょう。
なお、イシューとマージリクエストの新規作成時にはこのCONTRIBUTINGへのリンクが表示されます。
イシューの新規作成画面の下の方にリンクがある
イシューを書くときに気をつけること(バグレポートを書く前にバグを検索してからなど)をCONTRIBUTINGに書いておくと、イシューを書く人が、この「すぐに気をつけること」に簡単にアクセスできます。
しかし、編集時には表示されませんし、残念ながらほとんどの人はこのリンクに気が付かないでしょう。
CHANGELOG
CHANGELOG.mdファイルはその名の通り、アプリケーションの修正履歴をまとめたものです。このファイル名も昔からの慣習です。
次のようにMarkdownで修正履歴を書いておくと、GitLabでバージョン一覧の目次を利用できます。
## 1.0.0 (2022-05-01)
- ログアウトできないバグを修正
- プロフィールページのXSSを修正
## 0.9.8 (2022-04-01)
- プロフィールにアバターを追加できるように
イシューの新規作成画面の下の方にリンクがある
LICENSE
LICENSEファイルはその名の通り、アプリケーションのライセンスを記載するためのものです。Markdownではなくテキストで拡張子なしで書くことが多いようです。
GitLabはLICENSEファイルを読み込み、プロジェクトトップページにそのライセンスを表示します。MIT Licenseのような一般的なOSSライセンスはその名前を、認識できない場合はOtherを表示します。
最後に
READMEはそのプロジェクトの様々な情報への入口です。READMEの完成度が高ければ、つられてGitLabに色んな情報が集まってきます。反対に完成度が低いと、分からないことをチャットなどで聞くことが多くなり、GitLabを活用する人が減っていくでしょう。
READMEを起点に開発ができるように、READMEを改善し続けましょう。
