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!