Readme Driven Development
9 likes2,278 views
The document discusses readme driven development and how to write effective readmes. It advocates writing the readme first to serve as a design document and roadmap for a project. It provides tips for readme structure and formatting, including using Markdown, limiting headings, highlighting code, and using proper punctuation. It also offers advice for writing style such as maintaining coherent state, understanding your audience, eliminating repetition, varying sentence structure, and avoiding the passive voice.
![Introduction
[W] is an [X] that does [Y]
through [Z]](https://image.slidesharecdn.com/readme-120503044151-phpapp02/85/Readme-Driven-Development-17-320.jpg)
Readme Driven Development
- 1. Readme Driven Development (and how to be a better writer) Mark Rickerby
- 3. UPPERCASE Traditionally used to denote human readable files
- 4. README FAQ INSTALL LICENSE AUTHORS CHANGELOG NEWS TODO
- 5. Read me! A call to action
- 6. Traditional view: Roadmap of a project
- 7. Traditional view: Explain file structure
- 8. Traditional view: Write at the last minute
- 11. Modern view: Statement of intent
- 13. Modern view: Write your Readme first
- 14. “It rewards you for keeping libraries small and modularized” – Tom Preston Werner
- 15. Mise en place www.antoniotahan.com
- 17. Introduction [W] is an [X] that does [Y] through [Z]
- 18. Getting Started Explain the steps to install and link to further info
- 19. Getting Started Show usage examples
- 20. Explore your API Write from a user perspective
- 21. ### POST Method Call the `post()` method to make an HTTP post request: ``` $http = new Net_Http(); $http->post($uri, $data); if ($http->getStatus() == 201) $body = $http->getBody(); ```
- 22. ### POST Method Call the `post()` method to make an HTTP post request: ``` $http = new Net_Http(); $response = $http->post($uri, $data); if ($response->getStatus() == 201) $body = $response->getBody(); ```
- 24. Use Markdown Or one of many alternatives
- 25. Sections as a guide Introduction • Summary Installation • Downloads • FAQ Getting Started • Examples Contributors
- 26. Structure Limit headings to H2 & H3 only
- 27. Formatting Use code to highlight keywords and examples
- 28. Punctuation Use real quotation marks: “double” or ‘single’
- 29. Punctuation Use en dash correctly: April–May Sydney–Melbourne Bose–Einstein
- 30. Punctuation Use em dash correctly: To break a thought—in a stronger way than using parentheses—an em dash should be used.
- 31. Writing well
- 32. Information that is necessary for successful communication Information that is helpful but not crucial Nice to know
- 33. Maintain coherent state Don’t assume knowledge that doesn’t exist yet
- 34. Understand tone Use the right language for the audience
- 35. https://github.com/play/play “It’s true. It’s in a README.”
- 36. https://github.com/chrisboulton/php-resque Lies! Lies!
- 37. Eliminate repetition Avoid using the same word or phrase over and over
- 38. Vary sentence structure Helps reading flow
- 39. Avoid the passive “The chicken crossed the road.” vs “The road was crossed by the chicken.”
- 40. “Never use a long word when a short one will do” – George Orwell
- 41. Driving projects with writing
- 43. Crowdfunding
- 45. A model for successful collaboration?
- 50. Thank you.