Day 1 - Clean up your README

Day 1 is here!

Let’s start with a few meta recommendations/rules for the challenge:

  1. The point of each exercise is to spend 20 minutes working on it, and to do this day after day. Much of the time, you will not be able to fully complete a challenge in the time allotted. This is okay. If you’re spending your 20 minutes each day, you’re doing it right. There’s no need for guilt, shame, or frustration here.

  2. I strongly recommend you attempt each exercise as the first thing you do in your work day. If you plan to fit it in “at some point today,” it’ll be super easy to never get around to it. If possible, try to get the exercise done before you even check email or Slack.

Onward to the exercise!

Today’s exercise: spend 20 minutes improving your README.

Why? Because it serves as your project’s welcome mat. A good README will save you time and frustration when new people join your project (as internal team members, or open-source contributors). It also serves as the sales pitch for your app or library.

Here are some ideas of things to add to your README to flesh it out:

If your codebase is a library:

  • The philosophy behind your tool
  • Its place in the ecosystem
  • A comparison to other similar libraries
  • Lots of usage examples (it’s hard to have too many of these)
  • Animated gifs

If your codebase is an app:

  • What role does it play?
  • How is it deployed?
  • Who on the team should people go to with questions?
  • What credentials are needed?
  • How do they install/boot/deploy/develop it?
  • What’s the development process?

For any project:

  • FAQs
  • Where should bugs be filed, and how?
  • Who should be asked for PR reviews? (Are PRs welcome, generally?)
  • How do you run tests?
  • Is there CI?
  • Screenshots

Here’s a nice README template that you should steal from liberally:

And here’s a collection of awesome READMEs that can help provide inspiration:

Set a timer for 20 minutes and get to it!

1 Like

Hey everyone,

I had a surprisingly fun time updating the READMEs for 3 of my projects today: 1 private app and 2 open-source ruby gems. You can find the updated READMEs for the gems here:

The READMEs for these gems have a similar structure.

I’m wondering if it’s still necessary to include a manual Table of Contents section, since GitHub now automatically generates one. However, I’m not sure how many people are aware of this feature or use it.

What do you think? Should I keep the manual Table of Contents, or can I remove it and rely on the one generated by GitHub?



I’m wondering if it’s still necessary to include a manual Table of Contents section, since GitHub now automatically generates one. However, I’m not sure how many people are aware of this feature or use it.

It could still be usefull if you got repo mirroring or to read README locally I guess :slight_smile:



I improved 3 readmes in the main projects maintained by my team. 2 of them only had 1 line so it was easy to improve them :joy:

As our team is small and rarely changes it did not feel especially useful, but can’t hurt either…

Done! :tada: – Cleaned up 2 READMEs; +94/-42 LOC.

Bonus: I’ve added to our CI/CD pipeline to have all READMEs spelling checked :slightly_smiling_face:


Done! It needed some love indeed.

If you are dealing with a library, I’ve found all-contributors to be an easy way to acknowledge everyone. I like that you can simply ping the bot from an issue or PR comment to add someone (eg. “@all-contributors please add john-smith for ideas and code”).

1 Like

Done, I did it in the front and the back part of my project. While I write it I found some things that I should change in the code.

Thanks @lud. I’ve tried I didn’t know it.

1 Like

Done for our monorepo and two of the individual apps.

Found some unused env variables and a serverless function I was able to delete because of it as well!

Just finished cleaning up the README on my primary project. And by cleaning up I mean… actually writing one haha. Thanks for the link to the template, it was very helpful.

1 Like

:white_check_mark: done! The 20 min timer was helpful :grin:


I’d probably remove it, fwiw.

1 Like

Done. I cleaned up the opening description to my personal site, listed the pre-reqs, and detailed Getting Started steps as a template user. The steps went under an ordered list. The “Awesome” examples, and efforts in this forum look great! Day 1, in. the books!

Decided to remove the table of contents.

Managed to get a decent start on a readme for an internal project. Definitely felt good with the 20 minute timer, reduced the overwhelming feeling that had stalled previous documentation attempts. Loving this start, can’t wait for day 2

Done, clearead readme in private repo also saved readme templates for future reference. Thanks! :smiley: Though I went a bit over than 20 mins xD

Done a little late, but it was the last day of vacation before works starts up tomorrow. Cleaned up READMEs for some personal projects at work.

I improved a readme for a private team repository. I updated more references, links, and practices than I expected! I should have listened and set the recommended 20-minute timer. I realized I was a half-hour in after what felt like the blink of an eye.

After reading others’ posts, I also noted to check out

It’s definitely been on my to-do list to improve the readability of our README files.
I’ve ran a few paragraphs through Grammarly for any mixup between American/Canadian/British spelling typos, and also started a translation folder ( using DeepL) to create additional README versions in Spanish, French, and Hindi.

Still debating if we should include more accessibility options (ie. providing different fonts for dyslexia readers)

A day late, but I’m back on track :smile:

Instead of our README, I discovered our Notion doc that is a collection of Learning Resources for the various tools and skillsets we use at work. I believe the page was a raw dump from a Github page, so the doc was in need of some formatting TLC. Lots of making freeform text into toggleable dropdown lists : )

Done… I had been meaning to reply to some feedback from 1 user for a little while, and this was the prompt.