Rework the README.md [ci skip]

Author: e2

README.md

@@ -2,47 +2,50 @@
 
 [![Gem Version](https://img.shields.io/gem/v/ruby_dep.svg?style=flat)](https://rubygems.org/gems/ruby_dep) [![Build Status](https://travis-ci.org/e2/ruby_dep.svg)](https://travis-ci.org/e2/ruby_dep)
 
-NOTE: For currently supported Ruby versions, [check out the Travis build status](https://travis-ci.org/e2/ruby_dep). If you need support for an different/older version of Ruby, open an issue with "backport" in the title and provide a compelling case for supporting the version of Ruby you need. When in doubt, open a new issue or [read the FAQ on the Wiki](https://github.com/e2/ruby_dep/wiki/FAQ).
+## Description
 
+RubyDep helps users avoid incompatible, buggy and insecure Ruby versions.
 
-## The problem
+It's for gem owners to add to their runtime dependencies in their gemspec.
 
-Your gem shouldn't (and likely doesn't) support all possible Ruby versions.
+1. It automatically sets your gemspec's `required_ruby_version` based on rubies tested in your `.travis-yml`
+2. It warns users of your project if they're using a buggy or vulnerable version of Ruby
 
-(And not all Ruby versions are secure to even be installed).
+NOTE: RubyDep uses it's own approach on itself. This means it can only be installed on Ruby versions tested here: [check out the Travis build status](https://travis-ci.org/e2/ruby_dep). If you need support for an different/older version of Ruby, open an issue with "backport" in the title and provide a compelling case for supporting the version of Ruby you need. 
+When in doubt, open a new issue or [read the FAQ on the Wiki](https://github.com/e2/ruby_dep/wiki/FAQ).
 
-You need a way to protect users who don't know about this. So, you need to tell users which Ruby versions you support in:
 
-1. Your gemspec
-2. Your README
-3. Your .travis.yml file
-4. Any issues you get about which version of Ruby is supported or not
+## Problem 1: "Which version of Ruby does your project support?"
 
-But, maintaning that information in 4 different places breaks the principle of
-single responsibility.
+Your gem shouldn't (and likely doesn't) support all possible Ruby versions.
 
-And users often don't really "read" a README if they can avoid it.
+So you have to tell users which versions your gem supports.
 
+But, there are at least 3 places where you list the Rubies you support:
 
-## The solution
+1. Your gemspec
+2. Your README
+3. Your .travis.yml file
+ 
+That breaks the principle of single responsibility.
 
-This gem helps you and your project users avoid Ruby version problems by:
+Is it possible to just list the supported Rubies in just one place?
 
-- warning users if their Ruby is seriously outdated or contains serious vulnerabilities
-- helps you manage which Ruby versions you actually support (and prevents installing other versions)
+Yes. That's what RubyDep helps with.
 
-How? This gems detects which Ruby version users are using and which ones your project supports.
+## Solution to problem 1
 
-It assumes you are using Travis and the versions listed in your `.travis.yml` are supported.
+Since Travis doesn't allow generated `.travis.yml` files, option 3 is the only choice.
 
-This helps you limit the Ruby versions you support - just by adding/removing entries in your Travis configuration file.
+With RubyDep, your gemspec's `required_ruby_version` can be automatically set based on which Rubies you test your gem on.
 
-Also, you it can warn users if they are using an outdated version of Ruby.
+What about the README? Well, just insert a link to your Travis build status page!
 
-(Or one with security vulnerabilities).
+If you're running Travis builds on a Ruby you support (and it's not in the "allow failures" section), it means you support that version of Ruby, right?
 
+RubyDep intelligently creates a version constraint to encompass Rubies listed in your `.travis.yml`.
 
-## Usage
+## Usage (to solve Problem 1)
 
 ### E.g. in your gemspec file:
 
@@ -65,32 +68,59 @@ If users see their Ruby version "green" on Travis, it suggests it's supported, r
 
 (Or, you can point to the rubygems.org site where the required Ruby version is listed).
 
+### In your `.travis.yml`:
+
+To add a "supported Ruby", simply add it to the Travis build. 
+
+To test a Ruby version, but not treat it as "supported", simply add that version to the `allowed_failures` section.
+
+
+## Problem 2: Users don't know they're using an obsolete/buggy/insecure version of Ruby
+
+Users don't track news updates on https://ruby-lang.org, so they may not know their ruby has known bugs or even serious security vulnerabilities.
+
+And sometimes, that outdated/insecure Ruby is bundled by their operation system to begin with!
 
-### In your library:
+## The solution to problem 2
+
+RubyDep has a small "database" of Ruby versions with information about which are buggy and insecure.
+
+If you like, your gem can use RubyDep to show those warnings - to encourage users to upgrade and protect them from nasty bugs or bad security holes.
+
+This way, when most of the Ruby community has switched to newer versions, everyone can be more productive by having faster, more stable and more feature-rich tools. And less time will be wasted supporting obsolete versions that users simply don't know are worth upgrading.
+
+This also helps users understand that they should nudge their hosting providers, managers and package maintainers to provided up-to-date versions of Ruby to that everyone can benefit.
+
+### Usage (to solve Problem 2)
+
+In your gemspec:
+
+```ruby
+s.add_runtime_dependency 'ruby_dep', '~> 1.1'
+```
+
+Somewhere in your library: 
 
 ```ruby
 require 'ruby_dep/warnings'
 RubyDep::Warning.show_warnings
+ENV['RUBY_DEP_GEM_SILENCE_WARNINGS'] = '1' # to ignore repeating the warning if other gems use `ruby_dep` too
 ```
 
-## Tips
+That way, as soon as there's a severe vulnerability discovered in Ruby (and RubyDep is updated), users will be notified quickly.
 
-To disable warnings, just set the following environment variable:
 
-`RUBY_DEP_GEM_SILENCE_WARNINGS=1`
-
-You can follow these rules of thumb, whether you use RubyDep or not:
+## Tips
 
-1. Avoid changing major version numbers, even if you're dropping a major version of Ruby (e.g. 1.9.2)
-2. If you want to support a current version, add it to your `.travis.yml` (e.g. ruby-2.3.1)
+1. To disable warnings, just set the following environment variable: `RUBY_DEP_GEM_SILENCE_WARNINGS=1`
+2. If you want to support a newer version of Ruby, just add it to your `.travis.yml` (e.g. ruby-2.3.1)
 3. To support an earlier version of Ruby, add it to your `.travis.yml` and release a new gem version.
-4. If you want to support a range of Rubies, include the whole range without gaps in minor version numbers (e.g. 2.0.0, 2.1.0, 2.2.0, 2.3.0) and ruby_dep will use the whole range. (If there's a gap, older versions will be considered "unsupported")
-5. If you just want to test a Ruby version (but not actually support it), put it into the "allow failures" part of your Travis build matrix. (ruby_dep ignores versions there).
-6. If you want to drop support for a Ruby, remove it from the `.travis.yml` and just bump your gem's minor number.
+4. If you want to support a range of Rubies, include the whole range without gaps in minor version numbers (e.g. 2.0, 2.1, 2.2, 2.3) and ruby_dep will use the whole range. (If there's a gap, older versions will be considered "unsupported").
+5. If you want to drop support for a Ruby, remove it from the `.travis.yml` and just bump your gem's minor number (Yes! Bumping just the minor if fine according to SemVer).
+5. If you just want to test a Ruby version (but not actually support it), put it into the `allow failures` part of your Travis build matrix. (ruby_dep ignores versions there).
 
 When in doubt, open an issue and just ask.
 
-
 ## Roadmap
 
 Pull Requests are welcome.