Update the Readme
Published: Jan 26th, 2021
This is part of Joyful Rails, a list of recommendations to make developing your Rails app more productive and joyful.
In this article, we are talking about updating the readme file.
Every time there is some new piece of information that every developer will need, or that is not obvious or easy to find, add that to the “readme” file.
Setting up a new development machine or onboarding a new developer is a great time to overhaul your readme file. Change anything that is incorrect, unclear, or missing.
Opening an unfamiliar codebase can be very intimidating. A readme file gives future developers a way to get their bearings. It can’t tell you where everything is, but it can let you know where to start looking – and that is huge.
Your readme file should probably include the name of the app, what it does, how to set up your development environment, how to run the tests, how to deploy, and any other information a new developer is likely to need.
This should go into a file called
Here is an example readme file:
# Hello World Universal greeter for all human and non-human entities ## Development Instructions on how to develop go here ### Specs `rake` ### Deployment `bin/deploy` ### Updating libraries `bin/gem_update`
In the long ago time, readme files were named
The all caps version of the file name makes it very easy to notice in a file listing.
.md extension indicates that the file is Markdown so it gets rendered
nicely in GitHub and elsewhere.