How to Write a Great README

Learning Goals

• Student has reviewed recommended practices and exemplars of strong READMEs
• Student is able to describe a template for a strong README
• Student has implemented the template by writing their own README

Mastery Expectation: HIGH. By the end of this lesson, students should feel completely confident in the skills listed here.

Why

We publish open source because we want people to use it, we want people to be impressed by it, or both. The first thing they’re going to do is check out the README. It’s our chance to make a first impression – done wrong it’ll be the only impression.

Warm Up

• When you’re using other tools for the first time, what’s been frustrating?
• What documentation have you seen that impressed you? Frustrated you?
• What makes a good pull request?

Structural Plan

• Research (5 min) & Collaborate (5 min)
• Group Share (12 min)
• Practice (15 min)
• Closing (3 min)

Research (16 min)

Today we’ll use a jigsaw technique to explore the topic of READMEs.

• Break into five groups of three
• Each group will explore one resource
• Read/explore on your own for 5 minutes using the guiding questions below
• Discuss your findings with your group for another 5 minutes
• Draw a set of key observations to share with the whole class

Resources

• Group 1: thoughtbot’s Blog
• Group 2: Dan Bader How to Write a Great Readme for Your GitHub Project note: you may have to click x on the ad to get to the page
• Group 3: TPW’s README-Driven-Development
• Group 4: Ponyfoo on README-Driven-Development
• Group 5: Jesse Luoto’s Blog

Purple Booth Readme Template

Guiding Questions

• If you had to distill the reading down to five key points, what would they be?
• Is there anything that stands out as surprising?
• How are the recommendations similar/different from traditional writing (like essays, books, etc)?
• Anything you disagree with or seems not worth the effort?

If you or your group finish early, browse these “awesome” READMEs and see if they comply with the recommendations you found.

Group Share (12 min)

Let’s bring our findings together through group discussion and post findings on the white board.

Practice (15 min)

It’s time to put it into practice. Get together with your group for Little Shop. Draft an amazing README, even if it includes features/descriptions you haven’t yet built, but will have when the project is delivered.

Closing (3 min)

• What key points are you going to keep in mind when writing a solid README?
• After today’s class, do you think you’ll go back and update README’s for your previous projects?