Readme Driven Development(and how to be a better writer)                  Mark Rickerby
UPPERCASETraditionally used to denotehuman readable files
README    FAQINSTALL   LICENSEAUTHORS   CHANGELOGNEWS      TODO
Read me! A call to action
Traditional view: Roadmap of a project
Traditional view: Explain file structure
Traditional view:Write at the last minute
Modern view:Statement of intent
Modern view:Design document
Modern view:Write your Readme first
“It rewards you for keeping libraries small and modularized” – Tom Preston Werner
Mise en place          www.antoniotahan.com
IntroductionOne paragraph summary
Introduction[W] is an [X] that does [Y]        through [Z]
Getting StartedExplain the steps to install and link to further info
Getting StartedShow usage examples
Explore your API  Write from a user    perspective
### POST MethodCall the `post()` method to make anHTTP post request:```$http = new Net_Http();$http->post($uri, $data);if ...
### POST MethodCall the `post()` method to make anHTTP post request:```$http = new Net_Http();$response = $http->post($uri...
Good style matters
Use MarkdownOr one of many alternatives
Sections as a guide    Introduction • Summary Installation • Downloads • FAQ   Getting Started • Examples           Contri...
StructureLimit headings to  H2 & H3 only
Formatting Use code to highlightkeywords and examples
PunctuationUse real quotation marks:   “double” or ‘single’
PunctuationUse en dash correctly:     April–May Sydney–Melbourne   Bose–Einstein
Punctuation   Use em dash correctly:To break a thought—in a stronger waythan using parentheses—an em dash           should...
Writing well
Information that is necessary for   successful communication       Information that           is helpful            but no...
Maintain coherent      stateDon’t assume knowledge that doesn’t exist yet
Understand toneUse the right language for      the audience
https://github.com/play/play“It’s true. It’s in a README.”
https://github.com/chrisboulton/php-resque                          Lies! Lies!
Eliminate     repetitionAvoid using the same word or phrase over and over
Vary sentence  structureHelps reading flow
Avoid the passive“The chicken crossed the road.”              vs “The road was crossed by the          chicken.”
“Never use a longword when a short  one will do”          – George Orwell
Drivingprojects with   writing
Crowdfunding
A model for  successfulcollaboration?
https://github.com/xenph/ignition
Thank you.
Readme Driven Development
Readme Driven Development
Readme Driven Development
Readme Driven Development
Readme Driven Development
Readme Driven Development
Readme Driven Development
Readme Driven Development
Upcoming SlideShare
Loading in …5
×

Readme Driven Development

2,668 views

Published on

Published in: Technology, Education

Readme Driven Development

  1. 1. Readme Driven Development(and how to be a better writer) Mark Rickerby
  2. 2. UPPERCASETraditionally used to denotehuman readable files
  3. 3. README FAQINSTALL LICENSEAUTHORS CHANGELOGNEWS TODO
  4. 4. Read me! A call to action
  5. 5. Traditional view: Roadmap of a project
  6. 6. Traditional view: Explain file structure
  7. 7. Traditional view:Write at the last minute
  8. 8. Modern view:Statement of intent
  9. 9. Modern view:Design document
  10. 10. Modern view:Write your Readme first
  11. 11. “It rewards you for keeping libraries small and modularized” – Tom Preston Werner
  12. 12. Mise en place www.antoniotahan.com
  13. 13. IntroductionOne paragraph summary
  14. 14. Introduction[W] is an [X] that does [Y] through [Z]
  15. 15. Getting StartedExplain the steps to install and link to further info
  16. 16. Getting StartedShow usage examples
  17. 17. Explore your API Write from a user perspective
  18. 18. ### POST MethodCall the `post()` method to make anHTTP post request:```$http = new Net_Http();$http->post($uri, $data);if ($http->getStatus() == 201) $body = $http->getBody();```
  19. 19. ### POST MethodCall the `post()` method to make anHTTP post request:```$http = new Net_Http();$response = $http->post($uri, $data);if ($response->getStatus() == 201) $body = $response->getBody();```
  20. 20. Good style matters
  21. 21. Use MarkdownOr one of many alternatives
  22. 22. Sections as a guide Introduction • Summary Installation • Downloads • FAQ Getting Started • Examples Contributors
  23. 23. StructureLimit headings to H2 & H3 only
  24. 24. Formatting Use code to highlightkeywords and examples
  25. 25. PunctuationUse real quotation marks: “double” or ‘single’
  26. 26. PunctuationUse en dash correctly: April–May Sydney–Melbourne Bose–Einstein
  27. 27. Punctuation Use em dash correctly:To break a thought—in a stronger waythan using parentheses—an em dash should be used.
  28. 28. Writing well
  29. 29. Information that is necessary for successful communication Information that is helpful but not crucial Nice to know
  30. 30. Maintain coherent stateDon’t assume knowledge that doesn’t exist yet
  31. 31. Understand toneUse the right language for the audience
  32. 32. https://github.com/play/play“It’s true. It’s in a README.”
  33. 33. https://github.com/chrisboulton/php-resque Lies! Lies!
  34. 34. Eliminate repetitionAvoid using the same word or phrase over and over
  35. 35. Vary sentence structureHelps reading flow
  36. 36. Avoid the passive“The chicken crossed the road.” vs “The road was crossed by the chicken.”
  37. 37. “Never use a longword when a short one will do” – George Orwell
  38. 38. Drivingprojects with writing
  39. 39. Crowdfunding
  40. 40. A model for successfulcollaboration?
  41. 41. https://github.com/xenph/ignition
  42. 42. Thank you.

×