README Workshop

Learning Goals

• Define as a class what makes a good (and bad) README.md file.
• Create a Readme file for the consultancy project.

Intro

Take a few minutes and write down your answers to the following questions:

1. What is a README?
2. Why do we as developers care about READMEs?

Solo Activity

Read through the resources linked at the bottom of this lesson, and pick out 3-5 best practices when creating/updating a Readme.

Then, take notes for ideas on what you’ll want to use in your Consultancy project’s README file.

Group Activity

1. As a class, share out ideas and your findings on what makes a good README file.

2. Walk through the READMEs and any documentation for one of the tools you’ve used so far in mod 3, and see how it holds up against our researched standards. Some examples include:

   • Figaro
   • Faraday
   • VCR

Workshop

Together with your partner/groups, take what you’ve learned from these resources and discussions, and begin (or continue) work on your Consultancy project’s README file. In the last few minutes of our session, we’ll share out your progress so far as inspiration to the other groups.

Resources

• https://thoughtbot.com/blog/how-to-write-a-great-readme
• https://dbader.org/blog/write-a-great-readme-for-your-github-project
• https://www.giacomodebidda.com/posts/how-to-write-a-killer-readme/
• https://tom.preston-werner.com/2010/08/23/readme-driven-development.html
• https://ponyfoo.com/articles/readme-driven-development
• https://thejunkland.com/blog/how-to-write-good-readme.html
• https://github.com/PurpleBooth/a-good-readme-template
• Mod 1 Lesson on Readmes