1. The problem
You're starting on a new project and your first major obstacle is making the damn thing run. 9 times out of 10 the README is outdated and you waste a full day making it work on your machine. Finally you make it work and your brain is flooded with dopamines. A great feeling similar to when you get released from a bear's death grip and realise that you're going to make it out alive. Your frustration at this point is so high that you don't even think of updating the README for the next poor sucker.
2. The solution
How do we break out of this madness? Instead of writing a README.md you should write a bash script. Call it FIRST_TIME_INSTALL.sh.
This script should follow the following principles:
- Automate as much as possible
Example: Instead of asking the user if docker is installed have the script check if docker is installed and if it isn't then install it. - Tell the human what is going on and why
Example: If you need to install MongoDB to run the project then print in the CLI why you're doing that. It could be as simple as: "Installing MongoDB because any serious app needs to persist data" - Account for different developer machines.
Example: If you have a dev team who is split between macOS and Ubuntu please make sure your script works for both operating systems
Why wouldn't this script get out of date? Couple of reasons:
- Developers would rather code than write documentation. Therefore it's more likely for them to keep the script up to date than the README.
- A script is easier to verify than documentation. When the script needs to evolve it's easy to test the script. The other developers should just need to run the setup script. If running the script doesn't allow you to start the application then the script doesn't work and needs to be adjusted.
- You can write tests for the setup script and put it in the CI/CD pipeline. This makes sense for large teams.
3. Getting practical
Grow the script incrementally like an oyster. Don't write the script with bells and whistles from the start. Write a basic script first and adjust it as you go. For example, don't make the script work for Ubuntu until you have your first ubuntu developer in the team. Ask him to adjust the script after he's figured out how to run your application on his machine.
I wanted to give a common setup script recipe but I'm already at 400+ words and no one likes long blog posts. If someone reaches out to me for the recipe I will write it.