Update the Readme
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.
When
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.
Why
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.
How
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 README.md
.
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`
Alternatives
In the long ago time, readme files were named README.txt
or README
or occasionally Readme
.
The all caps version of the file name makes it very easy to notice in a file listing.
The .md
extension indicates that the file is Markdown so it gets rendered nicely in GitHub and elsewhere.