READMEs: The What and The Why
Learning Goals
- Understand the reasons for writing a solid README
- Determine what to include in a README
- Use your README as a tool for your eventual job search
Vocab
Markdown: a lightweight markup language for creating formatted text using a plain-text editor; we use this for READMEsREADME: a form of documentation for a project directory
Warm Up
In your breakout rooms…Pretend like you’re in an interview and your interviewer asks you to talk about your first paired project in Mod 1. Take turns responding to that prompt. Then discuss:
- What was easy about answering this question?
- What was difficult?
- What would make it easier for you to answer this question in the future?
The Why
We often think of READMEs as an afterthought in our projects, but they are SO important! Here are some ways that READMEs matter to you and your eventual job hunt:
- To an employer, your README is often the first impression of the work you’ve done
- Sometimes employers only scan the README and don’t even open the project
- Your README is how someone knows how to access your project (It should be written in a way that non-technical people can understand)
- The README documents your experience and process to an employer (which is way more important than the project itself!)
- Looking back at past READMEs is a great way to remind yourself of all you’ve done and prepare for interviews
- Taken cumulatively, your READMEs document your technical and professional growth
Judging READMEs
In your breakout rooms, look through the READMEs below. We’re going to go for first impressions here, so spend about 1 minute per README. Make some observations about the READMEs and add some stickies to this Jamboard
README Links:
Let’s share some takeaways!
Here are some that we came up with:
- Too many images can make it too chaotic
- When information isn’t shared in a logical order, it’s hard to follow
- Deploy links and install instructions should be one of the first things you see
- Lacking information can make it impossible to open the application or hit the endpoints
Cohort Challenge
Now that we’ve judged other READMEs, let’s practice some humility and have some fun. Take a few minutes to look through your past project READMEs and find your worst one.
Your cohort is now competing for the prize of Worst README! Raise your hand if you’d like to join the competition. Take turns screensharing and then vote for the worst!
Now recognize that we’re focused on growth here! Let’s get better!
The What
So what should we include in a README? Well, it’s not a one-size-fits-all thing. Depending on your project, what you’re the most proud of, etc., you may want to highlight different things in your README. Here are some things we recommend including:
- Set Up Instructions
- Deploy Link (if applicable)
- Abstract/Elevator Pitch (what problem is app trying to solve?)
- Contributors (including who owned what pieces?)
- Links to Wireframe/Planning docs (if applicable)
- Tech Stack (including testing + accessibility)
- Context (time allotted, # of people, mod, learning goals)
- Wins/Challenges (personal or team)
- Future Additions (these should be entered as Issues and on your Project Board as well)
- ONE gif (show the highest impact feature of your app)
- You can add comments in your README for things you want to document but don’t want shown (just remember these are still viewable to everyone in the raw file)
Obviously including all of this would be a bit much. Think about - What do you want someone to know about this project AND what do you want to remember about this project?
Updating a README
Choose one README from a past project and make some updates to it based on what you’ve learned in this lesson.
Revisiting the Warm Up
In your breakout rooms…Pretend like you’re in an interview and your interviewer asks you to talk about the project you just updated your README for. Take turns responding to that prompt. Then discuss:
- Was this easier to answer than the Warm Up question? Why?
- What work do you need to do on your own to get your READMEs up to par?
