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?)
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:
My first day started great, I managed to get the task done first thing in the morning
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
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.
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.
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.
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 – A template to make good README.md · GitHub which does the job. Thanks for sharing this!
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
Looking forward to all the code quality challenges!
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!
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.
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.
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.
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.
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.
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.
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.
Also, kudos for suggesting spending those 20 minutes first thing. That’s a pretty good life-hack in general.
So, this I fun, glad to be on board. My log of the day:
