Readme driven development AS Tech Talk 2014/10/15 at Shinjuku Grand Tower

1. Readme Driven Development
@koudaiii

2. Profile
id: koudaiii
fullname: Kodai Sakabe

3. Attention
• ウォーターフォール型とは区別
• SIerが作るExcel設計書とは別物
• しかし、ドキュメント駆動開発の一部

4. Agenda
• README
• 課題
• Readme driven development
• 落穂拾い

5. README

6. Gox
https://github.com/mitchellh/gox
README.md

7. $ man hub
$ man hub
!
HUB(1)
!
NAME
hub - git + hub = github
!
SYNOPSIS
hub [--noop] COMMAND OPTIONS
hub alias [-s] [SHELL]
!
Expanded git commands:
git init -g OPTIONS
git clone [-p] OPTIONS [USER/]REPOSITORY DIRECTORY
git remote add [-p] OPTIONS USER[/REPOSITORY]

8. 個人で
何かのツールを作る時

9. 今まで自分の失敗談
• 何かを作る際に、他者を巻き込むと謎のプロセス標
準の設計書を求められたりと急に大掛かりになって
ツライ
• かと言って、先に作ったのはいいけどドキュメント
を今更書くのがツライ
• ドキュメントなしだと、そもそも出来上がったもの
がぶれていたり、同じ説明を複数回するのがツライ

10. ようは、、
• 精巧なドキュメントを強いられるのがしんど
い
• 出来た後にドキュメントを書くのがしんどい
• 書かないとぶれやすいし、使ってもらえない

11. Readme Driven Development

12. Write your Readme first.

13. Readme Driven Development
• 創ろうと思った時が一番モチベーションが高い
➡ 出来上がった時にはもう書かれない‥
• 作る前の精巧なドキュメントはモチベーションを下げる
➡ ライターじゃないんだよ！！
• 一番腰が上がっているうちに簡単なドキュメント
➡README！

14. 最初にREADMEを書くことで
• しっかり名前を考える
• そもそも何をするためのものなのか（やれること、やれな
いこと、やらないこと）
• 使い方を書く(インターフェース、パラメーター)
• 先に書くことで「あーここ漏れてるわ」て気づきやすい
• (なぜ、これを創ろうと思ったかの背景を書いてもいいかも)

15. 最初にREADMEを書くことで
• 最初に書くことでユーザーの方を向くことができる
• Amazonでは、プレスを書いてからやる
• PullRequestを出す前にやることを書くとぶれにくい
• 回り道を防ぐ。
• (そもそも何がやりたかったんだっけ？と立ち戻る)

16. README.md
Name
====
!
Overview
!
Description
————
!
Usage
————
!
Install

17. READMEに書くこと
(なにこれ？)
• Name 名前
• Overview 一言で概要
• Description 概要の詳細
• Demo GIFアニメ貼ったり:)

18. READMEに書くこと
(どうやって使う？)
• Requirement 依存関係があれば書く
• Usage 使い方(この辺はコピペでできること)
• Install インストール方法(こっちもコピペで
きること)

19. READMEに書くこと
(その他)
• Contribution 参加方法
• LICENCE ライセンス
• Document wikiでまとまってるページあればリンク貼る
• Ticket チケット化されている場合はリンクを貼る
• Deploy リリース方法
• Test テストを行う方法

20. 落穂拾い

21. チケットやWIP書く時にも有効
• チケット
• 動作を発生させるための手順
• その中で、問題と思っている箇所
• その問題と思っている箇所は、実際にどういう風になっているべきか
• おまけ そしてその理由（任意）
• 思い出せるチケットの書き方: 「動機」、「ゴール」、「実現案」
• http://www.clear-code.com/blog/2012/7/12.html
※自分のプロジェクトで書いたルール抜粋してきました

22. WIP(Work In Progress) Pull Request
空コミットでPull Requestを送り⇒コメント欄にTODOリストを作りチェッ
クボックスを追加⇒早い段階でタスクの宣言と共有が早い段階でできる

23. Reference
• Rebuildfm（ep.52:27m20s~）
• http://rebuild.fm/52/
• Readme Driven Development
• http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
• Readme駆動開発を和訳してみた
• http://syossan.hateblo.jp/entry/2014/08/04/165746
• わかりやすいREADME.mdを書く
• http://deeeet.com/writing/2014/07/31/readme/
• How to Write a Readme Worth Reading
• http://orchestrate.io/blog/2014/07/16/how-to-write-a-readme-worth-reading/
• アジャイルが否定したものを見直そう
• http://arclamp.hatenablog.com/entry/2014/09/13/182244