Successfully reported this slideshow.
Your SlideShare is downloading. ×

Readme driven development

Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Upcoming SlideShare
Pull Request & TDD 入門
Pull Request & TDD 入門
Loading in …3
×

Check these out next

1 of 23 Ad
Advertisement

More Related Content

Recently uploaded (20)

Advertisement

Readme driven development

  1. 1. Readme Driven Development @koudaiii
  2. 2. Profile id: koudaiii fullname: Kodai Sakabe
  3. 3. Attention • ウォーターフォール型とは区別 • SIerが作るExcel設計書とは別物 • しかし、ドキュメント駆動開発の一部
  4. 4. Agenda • README • 課題 • Readme driven development • 落穂拾い
  5. 5. README
  6. 6. Gox https://github.com/mitchellh/gox README.md
  7. 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. 8. 個人で 何かのツールを作る時
  9. 9. 今まで自分の失敗談 • 何かを作る際に、他者を巻き込むと謎のプロセス標 準の設計書を求められたりと急に大掛かりになって ツライ • かと言って、先に作ったのはいいけどドキュメント を今更書くのがツライ • ドキュメントなしだと、そもそも出来上がったもの がぶれていたり、同じ説明を複数回するのがツライ
  10. 10. ようは、、 • 精巧なドキュメントを強いられるのがしんど い • 出来た後にドキュメントを書くのがしんどい • 書かないとぶれやすいし、使ってもらえない
  11. 11. Readme Driven Development
  12. 12. Write your Readme first.
  13. 13. Readme Driven Development • 創ろうと思った時が一番モチベーションが高い ➡ 出来上がった時にはもう書かれない‥ • 作る前の精巧なドキュメントはモチベーションを下げる ➡ ライターじゃないんだよ!! • 一番腰が上がっているうちに簡単なドキュメント ➡README!
  14. 14. 最初にREADMEを書くことで • しっかり名前を考える • そもそも何をするためのものなのか(やれること、やれな いこと、やらないこと) • 使い方を書く(インターフェース、パラメーター) • 先に書くことで「あーここ漏れてるわ」て気づきやすい • (なぜ、これを創ろうと思ったかの背景を書いてもいいかも)
  15. 15. 最初にREADMEを書くことで • 最初に書くことでユーザーの方を向くことができる • Amazonでは、プレスを書いてからやる • PullRequestを出す前にやることを書くとぶれにくい • 回り道を防ぐ。 • (そもそも何がやりたかったんだっけ?と立ち戻る)
  16. 16. README.md Name ==== ! Overview ! Description ———— ! Usage ———— ! Install
  17. 17. READMEに書くこと (なにこれ?) • Name 名前 • Overview 一言で概要 • Description 概要の詳細 • Demo GIFアニメ貼ったり:)
  18. 18. READMEに書くこと (どうやって使う?) • Requirement 依存関係があれば書く • Usage 使い方(この辺はコピペでできること) • Install インストール方法(こっちもコピペで きること)
  19. 19. READMEに書くこと (その他) • Contribution 参加方法 • LICENCE ライセンス • Document wikiでまとまってるページあればリンク貼る • Ticket チケット化されている場合はリンクを貼る • Deploy リリース方法 • Test テストを行う方法
  20. 20. 落穂拾い
  21. 21. チケットやWIP書く時にも有効 • チケット • 動作を発生させるための手順 • その中で、問題と思っている箇所 • その問題と思っている箇所は、実際にどういう風になっているべきか • おまけ そしてその理由(任意) • 思い出せるチケットの書き方: 「動機」、「ゴール」、「実現案」 • http://www.clear-code.com/blog/2012/7/12.html ※自分のプロジェクトで書いたルール抜粋してきました
  22. 22. WIP(Work In Progress) Pull Request 空コミットでPull Requestを送り⇒コメント欄にTODOリストを作りチェッ クボックスを追加⇒早い段階でタスクの宣言と共有が早い段階でできる
  23. 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

×