Make installation instructions consistent
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 944
- Forks
- 673
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 9
Description
If you do this:
- Visit https://www.ruby-lang.org/
- Click the large DOWNLOAD RUBY call to action
- Scan to he first appearance of macOS
then you are encouraged to use rbenv or RVM to install Ruby.
But if you:
- Search the internet for "install ruby"
- Land on https://www.ruby-lang.org/en/documentation/installation/
- Scan for the first appearance of macOS
then you are encouraged to install Ruby using Homebrew.
These two different ways of installing Ruby are extremely different. And they lead to different outcomes. For example, I have been using Ruby on macOS for 5 or 10 years, contribute to major projects and I still cannot reliably make Ruby work on macOS, especially when using Jekyll or Bundler or even rbenv. Please do not respond to this part, please simply let me make the point without further debate that properly installing Ruby can be frustrating for at least one person.
Recommendation
The Ruby project should internally decide one specific preferred installation strategy for macOS. It should then promote that preferred approach prominently (i.e. above other competing instructions) on all its published pages regarding to installing Ruby.
Completing this will allow people to achieve a supported Ruby installation by using the Universal UNIX Software Installation approach:
- Delete the software using all the ways that didn't work.
- Find the project's website.
- Find some instructions on there.
- Follow the first applicable instructions you see.
Currently Ruby is not compatible with the Universal instructions because step 3 results in competing instructions.
After this is complete, please consider opinionated and consistent install instructions platforms other than macOS.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the macOS guidance reached through the ruby-lang.org download call to action with the documentation/installation page. Review the competing rbenv, RVM, and Homebrew recommendations and determine the project's preferred strategy; done means that one approach is consistently prominent across published installation pages.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100