このブログをご覧のみなさん、こんにちは。

ちょうど見ているサービス(not 社外)の README¹が超絶分かり易いものではなく、毎日毎日悪戦苦闘しているけどそれでも全然前に進めないので、これを反面教師に分かり易い README について考えてみました。

RubyGems に Gem として公開する際、以下のコマンドで生成されるREADME.mdを下地に何点か追加しています。

$ bundle gem gemname -t

以下が考えてみたREADME.mdのテンプレートです。

# Name
Description
## Demo
## Requirements
## Installation
## Usage
## Contributing
## License
※個人アカウントではない場合
## Author
※以下社内リポジトリの場合
## Documents
## Issues
## Environments
### Test
### Deploy

次にテンプレートの各項目について説明します。

このサービス/ライブラリ/ツールは何なのか？

Name

このサービス/ライブラリ/ツールの名前を一番上に書きます。これは bundle gem で生成した README.md と同じです。

Description

このサービス/ライブラリ/ツールの概要と説明を名前のすぐ下に書きます。これもbundle gemで生成した README.md と同じです。

Demo

これはbundle gemで生成したREADME.mdにはなく、自分であったらよいのでは？と思って追加したものです。文書で機能を伝えられればよいですが、百聞は一見に如かずという言葉の通り、実際の動作を見てもらった方がよく理解できると思います。

どうやって使うのか？

Requirements

このサービス/ライブラリ/ツールを使うのに前提条件がある場合は、その依存を書きます。これもbundle gemで生成した README.md と同じです。

Installation

このサービス/ライブラリ/ツールをインストールする方法を書きます。コピペするだけで実行できるように書くとよいと思います。これもbundle gemで生成した README.md と同じです。

Usage

このサービス/ライブラリ/ツールの使い方を書きます。オプションがある場合はそれも説明を書くとよいと思います。コマンドだけでは伝えられない場合はテストにリンクしてそれを見せるのもよいと思います。これもbundle gemで生成した README.md と同じです。

貢献する方法は？

Contributing

このサービス/ライブラリ/ツールへ貢献する方法を書きます。これもbundle gemで生成した README.md と同じです。

ライセンスは？

License

このサービス/ライブラリ/ツールのライセンスを書きます。ライセンスを明示することで、このサービス/ライブラリ/ツールを使う側に安心感を与えられます。これもbundle gemで生成した README.md と同じです。

オーナーは？

Author

これはbundle gemで生成した README.md にはなく、自分であったらよいのでは？と思って追加したものです。個人アカウントのリポジトリではない場合はオーナーを書きます。

より詳細な情報は？

Documents

リポジトリ外にこのサービス/ライブラリ/ツールの情報がある場合はそこへのリンクをまとめとして書きます。

Issues

リポジトリ外でチケット管理をしている場合は、そこへのリンクを書きます。

Test

テストの方法やテスト環境を書きます。

Deploy

デプロイの方法を書きます。

まとめ

• 分かり易くない README は長くそれに関わっているメンバーには問題ありません
• しかし、新しく関わるメンバーには非常に負担になります
• リポジトリは生き物なので、分かり易く整備していくとよいと思います