Let’s start with a few meta recommendations/rules for the challenge:
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.
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?)
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
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”).
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.
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!
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
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 vale.sh.
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)
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 : )
– Cleaned up 2 READMEs; +94/-42 LOC.
done! The 20 min timer was helpful 
Though I went a bit over than 20 mins xD