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 (async)

1. In your consultancy project slack channel, one person should create a thread called “README discussion”.

2. Each member of the consultancy group will use this thread to share out ideas and your findings on what makes a good README file.

3. Each member of the consultancy group will choose one of the tools you’ve used so far in mod 3, and in your README thread, summarize how that tool’s documentation/README holds up against our researched standards.

Some examples include:

• Faraday
• VCR
• React Router
• Cypress

Workshop

1. In your consultancy project slack channel, one person should create a thread called “README action items”.
2. Use this thread to identify and agree upon 1-2 items to add to your project READMEs (or improve upon). Make sure to create an issue on your project board for each item.
3. One person will tag your PM in this thread. This serves as your ‘exit ticket’ for this async lesson.

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