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!

10 Likes

My first day started great, I managed to get the task done first thing in the morning :sunglasses:

I added a README to an internal project that had none. It made me realize two things and ask one thing.

  • There are no automated tests in this project :roll_eyes:
  • Future me will be happy to not have to remember how to do certain things

The question that popped up is the following: How do I prevent a stale README in the future?
Would it work to have scripts/setup, script/install and script/run in the project instead of having detailed instructions in the README that need to be kept up-to-date.

Has anybody experience with that?

5 Likes

It was a really informative first day. Added a Readme to a community website project. Readme .

I have noticed that a lot of projects follow the same structure of README in a lot of different use cases. A resource that I think is really helpful if someone is looking for a README template is github repo link.

Looking forward to the next day :slight_smile:

1 Like

Having a script can be really beneficial but it mostly depends on the project. If it’s an Open source collaborative project then I would prefer a detailed Readme as I am not sure to what level of knowledge my audience is going to have.

1 Like

Added a README to my own private project which didn’t have one in the first place. I made a clone of mine from this standard template – https://gist.github.com/PurpleBooth/109311bb0361f32d87a2 which does the job. Thanks for sharing this!

1 Like

Polished a README that was created a few months ago for a new greenfield project at work. It was a bit stale and I never found time to update it, so this was the perfect opportunity :sweat_smile:

Looking forward to all the code quality challenges!

1 Like

Great start into the challenge!

I created a README for a private repo that is part of my course and I can’t share publicly, unfortunately, but 20 minutes were just enough to include

  • setup instructions
  • GIFs of the actual application (good to have them in advance!)
  • copyright notice

In case anyone finds it useful, here’s an ffmpeg snippet I use to convert screenrecordings into GIFs:

ffmpeg -i in.mov -filter:v "setpts=0.5*PTS, scale=600:-1" out.gif

The filters speed up the GIF by 0.5 and scales it to a width of 600, keeping aspect ratio (both useful because GIFs are usually laaaaaaarge)

3 Likes

Thank you for the challenge! Great start.

I created a README for the new project that I started to work on at my workplace. It was regarding a new webapp that is being made, added some basic details considering the project is just getting started.

  • Setup Instruction
  • project structure and details
  • resources

Will keep on adding more to it on the go as the project progresses. Looking forward to next day!

1 Like

Tried to improve Readme, but in 20 minutes haven’t accomplished much. Only screenshot took 3rd part of the time.

1 Like

20 minutes fly by! As I don’t have any OS projects I can share content from, I used this assignment to initiate an app idea I’m having for a while now. So for the readme I focused on the most important information, which is the why behind the idea.

I set it up to communicate clearly that it’s open source. Though, I currently won’t accepts PR’s until I have an initial version working. I communicated this clearly more to prevent people from spending their precious time on possible PR’s I won’t merge for now.

1 Like

Have improved the ReadMe with instructions to setup and start the app. Looking forward for the next ones.

2 Likes

I took the opportunity to improve the instructions on how to run e2e tests. They were not clear (and a bit wrong) and several people wasted time because of that in the past.

Looking forward to day 2 :slight_smile:

1 Like

Thanks for the great resources! Today’s challenge helped me take a side project one step closer to publication, thanks :slight_smile:

Anyone using sublime text?

I used this to generate previews from the markdown (saves a push to GitHub, for example):
https://packagecontrol.io/packages/MarkdownPreview

1 Like

I took this opportunity to improve the README of my side project. 20 mins just went like that. But that write up helped me realised few things which was missing. Looking forward to next challenge.

1 Like

I used the opportunity to add a project structure description to the readme to make it easier for new team members to get an overview of the responsibilities of our different modules in the project.

1 Like

I had a chance to improve my readme by adding more examples how to work with the codebase: how to do setup, run tests, seed data, run the app and deploy, also updated dependencies and tech stack.

1 Like

I updated the readme an app I am working on at the moment; it was never the right time to update it since there are a lot of moving parts. But spending 20 minutes on it was the right call, my future self will approve.

2 Likes

Excellent call because I literally never did that. Most of the projects I work on are internal, but even for those, it is already helping to put, for example, deployment Infos in there, environment variables, common commands (how to run migrations in prod), etc.
Writing it down is definitely much better than putting pieces back together when you revisit a project after two years or so, which is what I usually do. :grimacing:

Also, kudos for suggesting spending those 20 minutes first thing. That’s a pretty good life-hack in general. :grinning:

So, this I fun, glad to be on board. My log of the day:

4 Likes

I spent the time to improve the “onboarding experience” of the readme for the next hire we are making. Excellent timing :clap:

2 Likes

Today’s task brought my attention back to the importance of the README. I have added README to work project I have recently started working on.

Looking forward to the next task!

1 Like