Readme Driven Development@koudaiii

Profile

id: koudaiii fullname: Kodai Sakabe

Attention• ウォーターフォール型とは区別

• SIerが作るExcel設計書とは別物

• しかし、ドキュメント駆動開発の一部

Agenda

• README

• 課題

• Readme driven development

• 落穂拾い

README

Goxhttps://github.com/mitchellh/gox README.md

$ 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]

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

今まで自分の失敗談• 何かを作る際に、他者を巻き込むと謎のプロセス標準の設計書を求められたりと急に大掛かりになってツライ

• かと言って、先に作ったのはいいけどドキュメントを今更書くのがツライ

• ドキュメントなしだと、そもそも出来上がったものがぶれていたり、同じ説明を複数回するのがツライ

ようは、、• 精巧なドキュメントを強いられるのがしんどい

• 出来た後にドキュメントを書くのがしんどい

• 書かないとぶれやすいし、使ってもらえない

Readme Driven Development

Write your Readme first.

Readme Driven Development

• 創ろうと思った時が一番モチベーションが高い

➡出来上がった時にはもう書かれない‥

• 作る前の精巧なドキュメントはモチベーションを下げる

➡ライターじゃないんだよ！！

• 一番腰が上がっているうちに簡単なドキュメント

➡README！

最初にREADMEを書くことで• しっかり名前を考える

• そもそも何をするためのものなのか（やれること、やれないこと、やらないこと）

• 使い方を書く(インターフェース、パラメーター)

• 先に書くことで「あーここ漏れてるわ」て気づきやすい

• (なぜ、これを創ろうと思ったかの背景を書いてもいいかも)

最初にREADMEを書くことで• 最初に書くことでユーザーの方を向くことができる

• Amazonでは、プレスを書いてからやる

• PullRequestを出す前にやることを書くとぶれにくい

• 回り道を防ぐ。

• (そもそも何がやりたかったんだっけ？と立ち戻る)

README.md

Name====!Overview!Description————!Usage————!Install

READMEに書くこと

(なにこれ？)• Name　名前

• Overview　一言で概要

• Description　概要の詳細

• Demo　GIFアニメ貼ったり:)

READMEに書くこと

(どうやって使う？)• Requirement　依存関係があれば書く

• Usage　使い方(この辺はコピペでできること)

• Install　インストール方法(こっちもコピペできること)

READMEに書くこと

(その他)• Contribution　参加方法

• LICENCE　ライセンス

• Document　wikiでまとまってるページあればリンク貼る

• Ticket　チケット化されている場合はリンクを貼る

• Deploy　リリース方法

• Test　テストを行う方法

落穂拾い

チケットやWIP書く時にも有効• チケット

• 動作を発生させるための手順

• その中で、問題と思っている箇所

• その問題と思っている箇所は、実際にどういう風になっているべきか

• おまけ そしてその理由（任意）

• 思い出せるチケットの書き方: 「動機」、「ゴール」、「実現案」

• http://www.clear-code.com/blog/2012/7/12.html

※自分のプロジェクトで書いたルール抜粋してきました

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

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