Readme Driven Development

  • 1,730 views
Uploaded on

 

More in: Technology , Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
1,730
On Slideshare
0
From Embeds
0
Number of Embeds
4

Actions

Shares
Downloads
19
Comments
0
Likes
8

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

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