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:
Set a timer for 20 minutes and get to it!
When you’re done, please chime in on the forum thread. How did the first day go for you? Are you aware of any resources that would help others complete the challenge? Please share them!
Off to a great start, I definitely needed to flesh out my README. The template you linked was invaluable, an immediate bookmark.
Generally, it’s hard to overstate how important it is to keep a README organized. When I’m looking through repositories for something to use or to solve a problem, a clean but thorough README is a really big indicator of project health and ease of use.
This was great! I went over the README from the app I work on a daily basis and figured out many of the key elements you mentioned were missing.
This will certainly speed up onboarding for new developers joining me, since so far I was going through every single detail with them (CI/CD, credentials, security scanners, etc).
Getting philosophy to be stated in my Github repo is a new thing to me, and I’ve improved my README by putting a TOC in it too. Did it by Markdown Preview and MarkdownTOC plugins in Sublime Text 3.
Hi.I am just rookie.Can anyone tell me what kind of application to develop. Whether it can be our own solution to a problem or exercises will be provided specifically by Leader
Couldn’t write much (just lack of knowledge of the project), but got basic setup instructions written down. Project had default template from Rails, so it was easy to improve it.
Great first exercise. My Trufflepiggy code base is seperated into many different project bundles but for the 20minutes I redid the readme for my Trufflepiggy - Context Search WebExtension.
Usually when I start a new project bundle I use the readme as a kind of brainstorming document but once the project is on its way all ideas are seperated into tickets and issues so the readme usually collects dust and doesn’t get updated anymore…
Total time used(excluding this follow up post): 23minutes.
I started with the app I’m working on (big refactoring branch).
The inherited readme was very light.
I copy/paste the one you mentioned and started filling it.
I took more than 20 minutes but now anybody can jump right in.
I will apply it to all the repos I manage.
A great starting point.
Thank you Ben. I can’t wait for the next challenge.
cya
I added deployment documentation on an Elixir Repo I’m working on.
The process is a bit complicated at this moment, it was necessary to add some documentation about it.
Most of the points were already taken care of. I took the chance to add a Contributing section with links to existing resources, added a Code of Conduct and mentioned the license in the readme.
All of my repos need great READMEs. But one of them now does have! Saving your advice for others. Thank you Ben for teaching to pay attention to the details. It’s very important to make a great product!
Really interesting to spend 20 minutes on a README; I quickly found how much information was missing from mine. At least one of them is in a much better state! CQC is helping already, thank you!
Good assignment, updated the readme of current project since it had some stale info.
We have a template that I created some time ago that we are using for most projects at the company I work for. We have a lot of projects with various technologies, so this template is created with that in mind and it’s not a good fit for everyone. But here is a slightly cleaned up version of our template if anyone else finds it useful:
Our READMEs had ancient information in it. Twenty minutes later, @danigirl329 and I have updated them and had some great discussion about what prerequisites are needed to start up our apps. Even better, a little bit of nostalgia on how far we have come.
I was pleasantly surprised that the README I chose to update wasn’t in as bad shape as I had feared! Still, it was useful to correct some of the rake task descriptions and the description of the data model, which I have changed but hadn’t documented.
.