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!
I spent the time to create a README in the git-repository for the big, old legacy project I’m working on most of the time. There’s very little documentation and everything that exists is in confluence.
Now I have a README which at least gives a brief explanation about the project and several links to the confluence pages.
I added a short description about what each of the repos are in my README but other than that, I prefer to have the documentation on Confluence instead of the README (for private repositories). I already had a very comprehensive getting-started guide that explains how to get all the repos, build them, and get the system up and running, so I added a link to that document.
There are two reasons why I keep the documentation out of the readme: it has a different development and release cycle than the code (weak reason) but also, I have three repos that interact with each other, so, I have a single document that explains how they all form the Dashman system and how to get it working.
This exercise reminds me that our latest team member were having difficulties in setting up docker, because some sample that we have in our readme were outdated and/or wrongly named… So I used this opportunity to improve our docker setup and update the related README…
Being the newest person on my team, the things that were outdated in our README were freshest in my head. Spent 20 minutes updating a couple of our setup steps, pointing to a few pertinent Wiki pages, explaining how shared password credentials are shared, and opening a PR for the updates.
We recently launched a new service at work with a dedicated API, but it all happened so fast no one put anything together for READMEs! I took my 20m today just add introductions and to templating out READMEs with the sections I think are needed for any future developer to be able to get up to speed, maintain, and extend the solution. Encouraged the whole team to participate in the CQC as well!
I added a section to the README for my primary freelance client about the expected Git workflow which makes heavy use of rebasing (something I’ve never been expected to do before) and which I recently had to figure out from experimentation and asking the other team members. Hopefully this makes onboarding any new developers a little easier!
This project already has pretty solid documentation so adding this was as simple as adding new sections to the existing documentation structure.
Our shop develops applications for internal use only, so we don’t deploy to clients nor do we have our applications on GitHub. I have shared one of our solutions with other institutions, so I added to the installation instructions that I wrote back then.
Updating the readme on our main project with fresh DB dumps & stuff for setup, and checking to make sure instructions are still accurate.
How do people generally share DB dumps for setting up a dev environment? I’d like them to be easily accessible to people who need them, but not easily downloadable for anyone who figures out the URL.
Just finished updating the README of my main personal project! It was quite up to date but still, a bit of cleanup + adding some information is always welcome. Hopefully this will make it easier for contributors to give a hand!
Looking forward to next days.
Just did the same last week, I guess we’re enthusiastic about all this
I added a README for my current client’s project which will be finished by end of this month. The README is meant for another developer who might be hired in future to make modifications. There is a good possibility that this another developer could be me one or two years down the line so in a way I have done my future self a favor
I added some notes in the README which point out certain known issues with the libraries/frameworks used. I would like to know from other community members, if they think README is the best place to list out such information or what alternatives do they practice?
How do people generally share DB dumps for setting up a dev environment? I’d like them to be easily accessible to people who need them, but not easily downloadable for anyone who figures out the URL.
I lately wrote a set of Powershell-scripts which will setup a new docker container (mssql-linux or oracle-linux), let the user choose which of the prepared backup files to be installed (provided via network-share) and installs it.
Network-internal share is the easiest way of course, but that depends on your environment.
Password-protected FTP is another easy-to-use way I can think of to share the dump-files (and even download automatically via script)
