- 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 thier own README
Mastery Expectation: HIGH. By the end of this lesson, students should feel completely confident in the skills listed here.
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.
- 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?
- 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
- Group 1: thoughtbot’s Blog
- Group 2: StackOverflow Discussion
- Group 3: The Frontier Group Blog
- Group 4: TPW’s README-Driven-Development
- Group 5: Ponyfoo on README-Driven-Development
- Group 6: Jesse Luoto’s Blog
- 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 posting findings on the white board.
Practice (15 min)
It’s time to put it into practice. Get together with your pair for Quantified Self. Draft an amazing README, even if it includes features/descriptions you haven’t yet built but will have when the project is delivered.
If you feel that your Quantified Self README is already amazing, look back at a previous project and improve that README.
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?