仕事であれ趣味であれソフトウェアを開発していると、READMEを記述する機会にしばしば出会う。READMEとは、配布物についての説明が記述された文書であり、その配布物を利用するにあたり最初に読むことを想定して記述されるものだ。そのような文書を、いざ自分で作成しようとすると、なかなか上手くいかない。READMEを記述することを面倒に感じ、そもそもREADME自体を作成しなかったり、ソフトウェアの名称だけを記載するのみになってしまったりする。
そのソフトウェアを作成した人の視点に立つと、その気持ちは理解できる。既に知っている事をわざわざ書く気にはならないし、何よりも多くの人はREADMEを読まないという肌感があるから、書こうという気にならない。一方でソフトウェアを使用する人の視点に立つと、違った状況が見えてくる。そのソフトウェアを作成した人と比較すると使おうとする人は、そのソフトウェアに対する情報を圧倒的に持っていない。それが何なのかも、インストールの方法も、使い方も知らない。だからドキュメントを探そうとするけれど、ドキュメントがどこにあるかも知らないし、READMEがないのにドキュメントがあるというのはあまり見たことがない。READMEは簡易なドキュメントであって、基本的なドキュメントだから、そういった利用者の助けになる。
しかし本当にREADMEを書くのは億劫だ。この億劫さは、何をどの順序でどの程度書けば良いのかということを考えたり校正したりする必要あり、それらは普段あまりやらない行為だからという理由から来ているのではないかと考えた。今回はこの億劫さを少しでもマシにするため、READMEについて考えることにした。
ユースケース別テンプレート
READMEとは何か、どうすべきかを考えるのは後して、まずはユースケース別テンプレートを作成した。READMEを読む人がどのような属性を持つ人かによって記述の内容は変わる。外部向けまたは内部向け、英語用または日本語用かによってユースケースを分けた。全て記述するというよりも、これを元にして必要ない所を削除し利用すると扱いやすい。
各項目について考えたことは、この次の章で記述している。READMEを使うという意味では全く読む必要はない。もしどうしても暇潰しが見付からなければ読むのも良いかもしれない。
外部向け
英語用
NAME [status badges] ======================== [概要を書く] [画像を入れる] ## Why? [なぜこれが必要だったのかを説明する] ## Other solutions [他のソリューションとの比較をする] [長所は書くが貶さない] ## Description [説明を書く] ### Demo [使うとどのように動くのかをビジュアルで説明する] ### Feature [どんな事ができるのかという機能の一覧を書く] [付随して何をサポートしないのかを書いても良い] ## How to use ### Usage [使い方を説明する] ### Requirements [動作させるためには何が必要かを書く] ### Install [インストール方法を書く] ## Contribution [貢献するための方法を書く] ### Document [ドキュメントの場所を書く] [ドキュメントの更新方法を書く] ### Issue [issueの管理場所を書く] [issueの作成方法を書く] ### Discussion [chatを書く] [定例もしくは定例の予定の確認方法を書く] ### Environment [環境を書く] ## License [ライセンスを書く] [社内向けなら社外秘であることを明示する] "hoge" is Confidential. ## Maintainer and Contributers [メンテナーを書く] [貢献してくれた人の一覧を書く]
日本語用
NAME [status badges] ======================== [概要を書く] [画像を入れる] ## なぜこれが必要か？ [なぜこれが必要だったのかを説明する] ## 他の選択肢 [他のソリューションとの比較をする] [長所は書くが貶さない] ### [説明を書く] ### デモ [使うとどのように動くのかをビジュアルで説明する] ### 機能 [どんな事ができるのかという機能の一覧を書く] [付随して何をサポートしないのかを書いても良い] ## 使い方 ### Usage [使い方を説明する] ### Requirements [動作させるためには何が必要かを書く] ### インストール [インストール方法を書く] ## コントリビューション [貢献するための方法を書く] ### ドキュメント [ドキュメントの場所を書く] [ドキュメントの更新方法を書く] ### Issue [issueの管理場所を書く] [issueの作成方法を書く] ### ディスカッション [chatを書く] [定例もしくは定例の予定の確認方法を書く] ### 環境 [環境を書く] ## ライセンス [ライセンスを書く] [社内向けなら社外秘であることを明示する] "hoge" is Confidential. ## メンテナとコントリビューター [メンテナーを書く] [貢献してくれた人の一覧を書く]
内部向け
英語用
NAME [status badges] ======================== [概要を書く] [画像を入れる] ## Description [説明を書く] ### Demo [使うとどのように動くのかをビジュアルで説明する] ### Feature [どんな事ができるのかという機能の一覧を書く] [付随して何をサポートしないのかを書いても良い] ## How to use ### Usage [使い方を説明する] ### Requirements [動作させるためには何が必要かを書く] ### Install [インストール方法を書く] ## Contribution [貢献するための方法を書く] ### Document [ドキュメントの場所を書く] [ドキュメントの更新方法を書く] ### Issue [issueの管理場所を書く] [issueの作成方法を書く] ### Discussion [chatを書く] [定例もしくは定例の予定の確認方法を書く] ### Environment [環境を書く] ## License [ライセンスを書く] [社内向けなら社外秘であることを明示する] "hoge" is Confidential.
日本語用
NAME [status badges] ======================== [概要を書く] [画像を入れる] ## なぜこれが必要か？ [なぜこれが必要だったのかを説明する] ## 他の選択肢 [他のソリューションとの比較をする] [長所は書くが貶さない] ### [説明を書く] ### デモ [使うとどのように動くのかをビジュアルで説明する] ### 機能 [どんな事ができるのかという機能の一覧を書く] [付随して何をサポートしないのかを書いても良い] ## 使い方 ### Usage [使い方を説明する] ### Requirements [動作させるためには何が必要かを書く] ### インストール [インストール方法を書く] ## コントリビューション [貢献するための方法を書く] ### ドキュメント [ドキュメントの場所を書く] [ドキュメントの更新方法を書く] ### Issue [issueの管理場所を書く] [issueの作成方法を書く] ### ディスカッション [chatを書く] [定例もしくは定例の予定の確認方法を書く] ### 環境 [環境を書く] ## ライセンス [ライセンスを書く] [社内向けなら社外秘であることを明示する] "hoge" is Confidential. ## メンテナとコントリビューター [メンテナーを書く] [貢献してくれた人の一覧を書く]
READMEとは
READMEとは、配布物についての説明が記述された文書であり、その配布物を利用する際、最初に読むことを想定して記述される。ファイル名や記述方法についての標準化された取り決めはない。しかし配布物の最上位のディレクトリに、 README だったり、 README. + その文書のフォーマットを示す拡張子 というファイルを配置するという慣習がある。
READMEで伝えるべき情報
READMEは利用者や関係者が最初に触れ、その後も最も接触機会の多い文書である。そのため、配布物の所有する全てのリソースを、READMEから辿ることができ、新しく使用や参加する人は、自分が次に何をすればよいか判断できるような文書になることが望ましい。その目的を達成しようとすると、記載したい内容はいくつか考えられるため、伝えるべき構成要素を整理することにした。
READMEは英語で記載することも多いため、英語では要素をどのように表現するのかということも記載した。また一般公開するような外部向けのものと、一般公開せず社内や組織内だけで共有するようなものとでは、記載内容に若干の差が発生することもある。そこで内部用と外部用のREADMEに対し、各要素の記載の必要性についても整理した。
| 要素 | English | 内部向 | 外部向 | 内容 |
|---|---|---|---|---|
| 名前 | Name | o | o | |
| ステータスバッジ | Status Badges | o | o | |
| アイキャッチ画像 | Eyecatch Image | x | o | |
| 概要 | Overview | o | o | |
| 解決する問題 | Why | x | o | なぜこれが必要だったのかを説明する |
| 他の選択肢 | VS | x | o | |
| 説明 | Description | o | o | |
| デモ | Demo | o | o | |
| 機能一覧 | Feature | o | o | |
| 使い方 | Usage | o | o | |
| 必要要件 | Requirements | o | o | |
| インストール | Install | o | o | |
| ドキュメント | Document | o | o | |
| リリース | Release | o | o | |
| バグ | Bug | o | o | |
| 討議 | Discussion | o | o | |
| プロジェクト管理 | Projects | o | o | |
| 環境 | Environment | o | x | |
| ライセンス | License | o | o | 社外秘であれば Confidential を明示する。 |
| メンテナー | Maintainer | x | o | |
| 謝辞 | Acknowledgments | x | o |
構成要素の記述内容と掲載順序
各項目をどのような順序で並べればよいだろうか。基本的には上部に記載するほどユーザーの目に入る回数は増える。そのため重要な情報ほど上部に記載するのが良いだろう。またアイキャッチ画像などはユーザーの注意を引くために作られているものであるから上部に記載するほうが良い。
名前
ユーザーは名前を元に対象を識別している。そのため名前は最も重要だろう。READMEの最上部に記載すると良い。多くのツールもそうしている。
アイキャッチ画像
アイキャッチ画像はユーザーの注意を引くための画像であり、ユーザーの注意を引き、またそのプロジェクトを表していることが望ましい。アイコンとしての役目も果たしている。それ以上の用途は特にないが、目的が注意を引くことであるから、目立つよう上部に載せるため、2番目の表示位置とした。
ステータスバッジ
ステータスバッジはCIやCDの現在の状態を表示する。これがきちんと整備や保守されているときちんと保守され続けているプロジェクトであると判断できる。これは開発者向けの情報である事が多いためもっと下に表示しても良いが、ステータスバッジ自体が小さく表示領域をあまり必要としないためアイキャッチ画像の下に配置すると良い。
概要
このプロジェクトの概要を記述する。ただしあまり文字が多くなってしまうと読む気が失せるので、必要最低限の概要に留める。主要な情報で万人に役立つ内容なのでなるべく上部が良い。
使い方
このプロジェクトが使用できるツールのようなものであるなら簡単な使い方を記述する。これは概要の次あたりが良い。その理由は、このツールを使う人には有用だが、プロジェクト管理者など、使用自体が目的でない人には必要が無い情報だからだ。
必要要件
このプロジェクトの提供する機能を動作させるために必要なシステム要件を記述する。これも使用自体が目的でない人には必要が無い情報だから使い方の後で良い。また使用者であっても環境を作成する初回しか必要のない情報だ。ただしインストール時には必要になるのでインストールの項目の前に記述すると良い。
インストール
このプロジェクトの配布物をインストールする方法を記述する。これも使用自体が目的でない人には必要が無い情報だから使い方の後で良い。また使用者であっても環境を作成する初回しか必要のない情報であるので、位置としては中段あたりでよい。よくあるプロジェクトのREADMEでは上部にインストールの記載があり、その後で使い方を説明しているものをしばしば見かける。もちろん明らかにそれが間違いということはないが、その記述が必要とされる回数を考えると中段ぐらいで良い。
機能一覧
このプロジェクトが提供する機能の一覧を記述する。完結に箇条書きで記述すると読む側も機能を把握しやすい。概要を上部に記述しているため、中段あたりに記述すると良い。
デモ
実際に動作しているとろのGIFアニメーションを貼り付ける。表示領域を多く取ってしまうので中段より下が良い。
説明
このプロジェクトや配布物の説明を記述する。以前で概要や機能については既に触れているため重複する記述は避け、既に記述した内容を補足する内容やもっと踏み込んだ内容を記述する。デモの後ろに記述があると、読者は内容をイメージしやすくなる。
解決する問題
どんな課題があったのか、どのように解決したのかを記述する。これがあると問題意識を共有しやすくなり、採用するかどうかの判断の助けとなる。説明の順序としては、問題があってその解決のために何を作ったのかを説明するとスムーズではあるが、機能だけに着目して機能を探している人にとっては、この情報は必要ないので、説明の後に配置するとよい。
他の選択肢
類似する問題を解決する別の選択肢があるのであればここに記述する。可能であれば比較表などを準備するとわかりやすくなる。解決する問題の次に記述すると背景を含めて理解しやすく、判断の助けになる。
プロジェクト管理
プロジェクト管理の方法を説明するか、又はURLを記述する。必要としている人が限られるため下部に記述すれば良い。
リリース
リリース情報と配布のURLを記述する。必要としている人が限られるため下部に記述すれば良い。
ドキュメント
ドキュメントのURLを記述する。必要としている人が限られるため下部に記述すれば良い。
バグ
バグトラッカーのURLを記述する。必要としている人が限られるため下部に記述すれば良い。
討議
チャットやメーリングリストなどのディスカッションの場があるのであればそのURLを記述する。必要としている人が限られるため下部に記述すれば良い。
環境
環境が用意されているのであれば環境へのアクセス手段を記述する。多くの人が必要としない情報のため下部に記述する。ここで言う環境とは本番環境や検証環境の事だ。
メンテナー
メンテナンスを行っている人と、その人への連絡手段を記述する。多くの人が必要としない情報のため下部に記述する。
謝辞
貢献してくれた人など、謝辞を送りたい人へのメッセージを記述する。多くの人が必要としない情報のため下部に記述する。
ライセンス
配布物のライセンスを記述する。社内用であればConfidentialを明記する。多くの人が必要としない情報のため下部に記述する。
まとめ
READMEについて考えたことをまとめた。またユースケース別のREADMEのテンプレートを作成した。この文書が誰かの役に立つことができたら嬉しい。
参考資料
- https://deeeet.com/writing/2014/07/31/readme/
- https://cpp-learning.com/readme/
- https://qiita.com/koeri3/items/f85a617dcb6efebb2cab
- https://karaage.hatenadiary.jp/entry/2018/01/19/073000
- https://tips-memo.com/python-readme
- https://blog.cles.jp/item/11372
- https://think-simple-enjoy-life.com/599
- https://github.com/sakura-editor/sakura/issues/1441
- https://un4navi.com/prologue/20079/