わかりやすい README 駆動開発

8992 ワード
Zsh Readme RDD GitHub Markdown Zsh テキストリンク

巷には README 駆動開発（Readme Driven Development; RDD）なるものがあるようで、とても合理的でかつ便利であったので紹介します。

README 駆動開発（以下、RDD）とはその名の通り、README ありきの開発スタイルのことで、簡単に言うと「コード書く前に README 書く」ってことです。
開発に入る前にドキュメンテーション、というまあ当たり前であるようでちょっとしたツールでは蔑ろにしがちなことですよね。

RDD のメリット

  • モチベーションが高いときに書ける

    正直、README 含めドキュメンテーションってめんどくさいです。しかし、コード書く前のインスピレーションとやる気に溢れているときに書くことで質の高い README が書け、コード完成後だとやるのがだるいドキュメンテーションの作業が完了します。

  • 要件定義につながる

    ドキュメンテーションを整備する前にコードを書き始めると、書いているうちに仕様が微妙に変わったり、追加したい機能などが出てきて Yak Shaving になったりしがちです。それを書き始める前に、これを整理することでスムーズなコーディングが可能です。

どんな README が優れているか

筆者の場合のテンプレートを紹介します。

README.md
# Awesome-name

![Badge Status](https://ci-as-a-service)

OverviewOverviewOverview

## Description

DescriptionDescriptionDescription
DescriptionDescriptionDescription
DescriptionDescriptionDescription

***DEMO:***

![Demo](https://image-url.gif)

## Features

- Awesome function
- Awesome UI
- ...

For more information, see `awesome-tool --help`.

## Requirement

- Requirement
- Requirement
- Requirement

## Usage

1. Usage
2. Usage
3. Usage

## Installation

    $ git clone https://github.com/b4b4r07/awesome-tool

## Anything Else

AnythingAnythingAnything
AnythingAnythingAnything
AnythingAnythingAnything

## Author

[@b4b4r07](https://twitter.com/b4b4r07)

## License

[MIT](http://b4b4r07.mit-license.org)

これは完成形の README です。つまり、GitHub に実際に Push するときのレイアウトです。RDD で書く README はもっと雑でもっとメモ書きに近いものです。「こんな機能」、「こんな感じ」、「こんなイメージ」というのを日本語でズラズラ書き連ねます。そういうことが要件定義につながり Features セクションにもつながります。

それぞれのセクションについて

筆者のリポジトリ b4b4r07/zgencomp を例に説明していきます。

  • # Awesome-name

    これはその通りプロダクトの名前です。筆者の場合、CLI ツールをよく作っていますが、その中でもよく利用するようなコマンドツールの場合は短めな名前（3文字以内が望ましい）で、あまり利用しないコマンドはわかりやすいような長めの名前をつけています。どんなプロダクトかで命名方法が変わるので、自分で作るプロダクトの業界について調べて、より慣習的な命名を心がけると良いです。

  • ![Badge Status](https://services-as-a-ci)

    これはビルドステータスのバッジです。テストを前提に作られたプロダクトはユーザに対して一定の保証を保つし、自分のコーディングのモチベーションにもつながるので、基本的に考えたほうが良い項目です。ない場合はここには何も来ません。

  • OverviewOverviewOverview

    これはプロダクトの一言紹介文です。端的に言い表したときの文章を考えましょう。GitHub の機能として提供されている「Description」に該当します。基本的には同一になるのが好ましいです。一文紹介という点で合致しますので。

  • ## Description

    プロダクトの大まかな概要です。2〜3文で言い表すのが好ましいです。

  • ***DEMO:***

    デモの用意をしましょう。使い方や動作のイメージは文章を読むより見たほうが早いです。ユーザが漠然ともつ「どう使うんだろう…」、「うわ、Usage 詳細だけど読むのめんどくさい…」といった不安感などを払拭するには GIF アニメを見せたほうが早いです。単体画像でもいいですがアニメーション画像のほうがいいでしょう。

  • ## Features

    プロダクトの持つ特徴や強みを列挙しましょう。多すぎる場合は、イチオシする機能などに絞り、マイナーな機能などは --help や man ページに誘導させましょう。

  • ## Requirement

    依存関係です。バージョンを指定する場合、Python3 or more や、Ruby 1.8+ といった書き方が慣習的です。

  • ## Usage

    使い方です。

  • ## Installation

    インストール方法です。git clone であったり、curl などのワンライナーであったりがより多いような気がします。
    最近は Go 製のプロダクトも多く、go get もよく目にします。

  • ## Anything Else

    自由記載のコーナーです。このセクションはあってもなくてもいいし、2つや3つあってもいい項目です。プロダクトによっては別個に説明が欲しかったり追記したい説明などがあると思います。その場合に活用するといいでしょう。セクション名も Anything Else である必要性もないので、適宜ふさわしいタイトルを付けます。

  • ## Author

    作者情報です。ここから他のプロダクトにつながる場合もあります。

  • ## License

    ライセンスです。これが明記されていない場合、GitHub が独自に認めるライセンスが自動で適応される仕組みになっているので注意しましょう。

大まかにはこのような流れになっていることが多いようです。筆者の場合はこのテンプレートを元に最終的な README を完成させています。REAMDE にフォーマットが作者内で統一されていると可読性が増すのでお勧めです（ユーザが作者Aの公開しているツールで初めて触ったものが良かった場合、作者Aのリンクを辿って他のツールを見ることがあるため）。

流れ的なポイントとして、優先順位は 「プロダクトの説明」＞「プロダクトに近しい詳細」（「Description、DEMO」＞「Installation、Usage」） です。ユーザは GitHub Readme のファーストビューでそのプロダクトを使うかどうかを判断します。概要やデモを見て使うか捨てるかを決めるのに、それが README の後ろに埋もれていて、最初の方に Installation や Usage が来るのは不親切な UI です。

まとめ

きれいな README が用意されているプロダクトってやはり使ってみたくなりますよね。自分のためにもユーザのためにも RDD いかがでしょうか。