Update Documentation and Installation pages (en)

Merge pull request #1877 from olivierlacan/official-api-docs

Author: JuanitoFatas

_config.yml

@@ -827,7 +827,7 @@ locales:
           description: |
             Get in contact with Rubyists in your area.
         weblogs:
-          text: Weblogs
+          text: Blogs
           url: /en/community/weblogs/
           description: |
             Read about what’s happening right now in the Ruby community.

en/documentation/index.md

@@ -4,32 +4,16 @@ title: "Documentation"
 lang: en
 ---
 
-Here you will find pointers to manuals, tutorials and references that
-will come in handy when you feel like coding in Ruby.
+Guides, tutorials and reference material to help you learn more about Ruby
 {: .summary}
 
 ### Installing Ruby
 
-Unless you only want to try Ruby in the browser (see the links below)
-you need to have Ruby installed on your computer.
-You can check whether Ruby already is available by opening a terminal
-and typing
-
-{% highlight sh %}
-ruby -v
-{% endhighlight %}
-
-This should output some information on the installed Ruby version.
-If not, see the [installation page](installation/) for various options
-of getting Ruby.
+Although you can easily [try Ruby in your browser][1], you can also read
+the [installation guide](installation/) for help on installing Ruby.
 
 ### Getting Started
 
-[Try Ruby!][1]
-: An interactive tutorial that lets you try out Ruby right in your
-  browser. This 15-minute tutorial is aimed at beginners who want to get
-  a feeling of the language.
-
 [Official FAQ](/en/documentation/faq/)
 : The official frequently asked questions.
 
@@ -43,14 +27,6 @@ of getting Ruby.
   through stories, wit, and comics. Originally created by *why the lucky
   stiff*, this guide remains a classic for Ruby learners.
 
-[Ruby in Twenty Minutes](/en/documentation/quickstart/)
-: A nice tutorial covering the basics of Ruby. From start to finish it
-  shouldn’t take you more than twenty minutes.
-
-[Ruby from Other Languages](/en/documentation/ruby-from-other-languages/)
-: Coming to Ruby from another language? Whether it’s C, C++, Java, Perl,
-  PHP, or Python, this article has you covered!
-
 [Learning Ruby][6]
 : A thorough collection of Ruby study notes for those who are new to the
   language and in search of a solid introduction to Ruby’s concepts and
@@ -85,6 +61,10 @@ of getting Ruby.
 
 ### Reference Documentation
 
+[Official API Documentation][40]
+: The official Ruby API documentation for different versions including
+  the currently unreleased (trunk) version.
+
 [Ruby Core Reference][13]
 : Pulled straight from the source code using [RDoc][14], this reference
   work documents all of the core classes and modules (like String,
@@ -191,4 +171,5 @@ If you have questions about Ruby the
 [37]: http://www.sublimetext.com/
 [38]: http://ruby.learncodethehardway.org/
 [39]: http://kapeli.com/dash
+[40]: https://docs.ruby-lang.org/en/
 [atom]: https://atom.io/

en/documentation/installation/index.md

@@ -4,35 +4,40 @@ title: "Installing Ruby"
 lang: en
 ---
 
-You can use several tools to install Ruby.
-This page describes how to use major package management systems
-and third-party tools for managing and installing Ruby
-and how to build Ruby from source.
+With package managers or third-party tools, you have plenty of options
+to install and manage Ruby.
 {: .summary}
 
+You may already have Ruby installed on your computer. You can check
+inside a [terminal emulator][terminal] by typing:
+
+{% highlight sh %}
+ruby -v
+{% endhighlight %}
+
+This should output some information on the installed Ruby version.
 
 ## Choose Your Installation Method
 
 There are several ways to install Ruby:
 
-* When you are on a UNIX-like operating system, using your system's
-  **package manager** is the easiest way of getting started.
-  However, the packaged Ruby version usually is not the newest one.
+* On a UNIX-like operating system, using your system's **package
+  manager** is easiest. However, the packaged Ruby version may not be
+  the newest one.
 * **Installers** can be used to install a specific or multiple
   Ruby versions. There is also an installer for Windows.
-* **Managers** help you to switch between multiple Ruby installations
+* **Managers** help you to switch between multiple Ruby versions
   on your system.
-* And finally, you can also **build Ruby from source**.
+* Finally, you can also **build Ruby from source**.
 
-The following overview lists available installation methods
-for different needs and platforms.
+Here are available installation methods:
 
 * [Package Management Systems](#package-management-systems)
   * [Debian, Ubuntu](#apt)
   * [CentOS, Fedora, RHEL](#yum)
   * [Gentoo](#portage)
   * [Arch Linux](#pacman)
-  * [OS X](#homebrew)
+  * [macOS](#homebrew)
   * [FreeBSD](#freebsd)
   * [Solaris, OpenIndiana](#solaris)
   * [Other Distributions](#other-systems)
@@ -55,20 +60,19 @@ for different needs and platforms.
 If you cannot compile your own Ruby, and you do not want to use a
 third-party tool, you can use your system's package manager to install Ruby.
 
-Certain members in the Ruby community feel very strongly that you should
-never use a package manager to install Ruby and that you should use tools
-instead. While the full list of pros and cons is outside of the scope
-of this page, the most basic reason is that most package managers have
-older versions of Ruby in their official repositories. If you would like to
-use the newest Ruby, make sure you use the correct package name,
-or use the tools described further below instead.
+Some members of the Ruby community feel that you should avoid package
+managers to install Ruby and that you should use dedicated tools instead.
 
+It's possible that major package managers will install older Ruby
+versions instead of the latest release. To use the latest Ruby release,
+check that the package name matches its version number. Or use a
+dedicated [installer][installers].
 
 ### apt (Debian or Ubuntu)
 {: #apt}
 
-Debian GNU/Linux and Ubuntu use the apt package manager.
-You can use it like this:
+Debian GNU/Linux and Ubuntu use the apt package manager. You can use it
+like this:
 
 {% highlight sh %}
 $ sudo apt-get install ruby-full
@@ -101,9 +105,9 @@ Gentoo uses the portage package manager.
 $ sudo emerge dev-lang/ruby
 {% endhighlight %}
 
-By default, this will try to install versions 1.9 and 2.0,
-but more versions are available.
-To install a specific version, set `RUBY_TARGETS` in your `make.conf`.
+By default, this will try to install versions 1.9 and 2.0, but more
+versions are available. To install a specific version, set
+`RUBY_TARGETS` in your `make.conf`.
 See the [Gentoo Ruby Project website][gentoo-ruby] for details.
 
 
@@ -120,13 +124,14 @@ $ sudo pacman -S ruby
 This should install the latest stable Ruby version.
 
 
-### Homebrew (OS X)
+### Homebrew (macOS)
 {: #homebrew}
 
-On macOS (High) Sierra and OS X El Capitan, Ruby 2.0 is included.
+Ruby versions 2.0 and above are included by default in macOS releases
+since at least El Capitan (10.11) all the way through Mojave (10.14).
 
-Many people on OS X use [Homebrew][homebrew] as a package manager.
-It is really easy to get a newer version of Ruby using Homebrew:
+[Homebrew][homebrew] is a commonly used package manager on macOS.
+Installing a Ruby using Homebrew is easy:
 
 {% highlight sh %}
 $ brew install ruby
@@ -178,48 +183,48 @@ latest version of Ruby.
 ### Other Distributions
 {: #other-systems}
 
-On other systems, you can search the package repository of your
-Linux distribution's manager for Ruby, or the third-party tools might be the
-right choice for you.
+On other systems, you can search the package repository of your Linux
+distribution's manager for Ruby. Alternatively, you can use a
+[third-party installer][installers].
 
 
 ## Installers
 {: #installers}
 
-If the version of Ruby provided by your system or package manager is out of
-date, a newer one can be installed using a third-party installer.
-Some of them also allow you to install multiple versions on the same system;
-associated managers can help to switch between the different Rubies.
-If you are planning to use [RVM](#rvm) as a version manager you do not need
-a separate installer, it comes with its own.
+If the version of Ruby provided by your system or package manager is out
+of date, a newer one can be installed using a third-party installer.
+
+Some installers allow you to install multiple versions on the same
+system; associated managers can help to switch between the different
+Rubies.
+
+If you are planning to use [RVM](#rvm) as a version manager you don't
+need a separate installer, it comes with its own.
 
 
 ### ruby-build
 {: #ruby-build}
 
-[ruby-build][ruby-build] is a plugin for [rbenv](#rbenv) that
-allows you to compile and install different versions of Ruby
-into arbitrary directories.
-ruby-build can also be used as a standalone program without rbenv.
-It is available for OS X, Linux, and other UNIX-like operating systems.
+[ruby-build][ruby-build] is a plugin for [rbenv](#rbenv) that allows you
+to compile and install different versions of Ruby. ruby-build can also
+be used as a standalone program without rbenv. It is available for macOS,
+Linux, and other UNIX-like operating systems.
 
 
 ### ruby-install
 {: #ruby-install}
 
 [ruby-install][ruby-install] allows you to compile and install different
-versions of Ruby into arbitrary directories.
-There is also a sibling, [chruby](#chruby), which handles switching between
-Ruby versions.
-It is available for OS X, Linux, and other UNIX-like operating systems.
+versions of Ruby into arbitrary directories. [chruby](#chruby) is a
+complimentary tool used to switch between Ruby versions. It's available
+for macOS, Linux, and other UNIX-like operating systems.
 
 
 ### RubyInstaller
 {: #rubyinstaller}
 
-If you are on Windows, there is a great project to help you install Ruby:
-[RubyInstaller][rubyinstaller]. It gives you everything you need to set up
-a full Ruby development environment on Windows.
+On Windows, [RubyInstaller][rubyinstaller] gives you everything you need
+to set up a full Ruby development environment.
 
 Just download it, run it, and you are done!
 
@@ -230,60 +235,60 @@ Just download it, run it, and you are done!
 If you are installing Ruby in order to use Ruby on Rails,
 you can use the following installers:
 
-* [RailsInstaller][railsinstaller],
-  which uses RubyInstaller but gives you
-  extra tools that help with Rails development.
-  It supports OS X and Windows.
-* [Bitnami Ruby Stack][rubystack],
-  which provides a complete development environment for Rails.
-  It supports OS X, Linux, Windows, virtual machines, and cloud images.
+* [RailsInstaller][railsinstaller] uses [RubyInstaller][rubyinstaller]
+  but gives you extra tools that help with Rails development. It
+  supports macOS and Windows.
+* [Bitnami Ruby Stack][rubystack] provides a complete development
+  environment for Rails. It supports macOS, Linux, Windows, virtual
+  machines, and cloud images.
 
 
 ## Managers
 {: #managers}
 
-Many Rubyists use Ruby managers to manage multiple Rubies.
-They confer various advantages but are not officially supported.
-Their respective communities are very helpful, however.
+Many Rubyists use Ruby managers to manage multiple Rubies. They allow
+easy or even automatic switching between Ruby versions depending on the
+project and other advantages but are not officially supported. You can
+however find support within their respective communities.
 
 
 ### chruby
 {: #chruby}
 
-[chruby][chruby] allows you to switch between multiple Rubies.
-chruby can manage Rubies installed by [ruby-install](#ruby-install)
-or even built from source.
+[chruby][chruby] allows you to switch between multiple Rubies. It can
+manage Rubies installed by [ruby-install](#ruby-install) or even built
+from source.
 
 
 ### rbenv
 {: #rbenv}
 
 [rbenv][rbenv] allows you to manage multiple installations of Ruby.
-It does not support installing Ruby, but there is a popular plugin
-named [ruby-build](#ruby-build) to install Ruby.
-Both tools are available for OS X, Linux, or other UNIX-like operating systems.
+While it can't install Ruby by default, its [ruby-build](#ruby-build)
+plugin can. Both tools are available for macOS, Linux, or other
+UNIX-like operating systems.
 
 
 ### RVM ("Ruby Version Manager")
 {: #rvm}
 
-[RVM][rvm] allows you to install and manage multiple installations of Ruby
-on your system. It can also manage different gemsets.
-It is available for OS X, Linux, or other UNIX-like operating systems.
+[RVM][rvm] allows you to install and manage multiple installations of
+Ruby on your system. It can also manage different gemsets. It is
+available for macOS, Linux, or other UNIX-like operating systems.
 
 
 ### uru
 {: #uru}
 
 [Uru][uru] is a lightweight, multi-platform command line tool that helps you
-to use multiple Rubies on OS X, Linux, or Windows systems.
+to use multiple Rubies on macOS, Linux, or Windows systems.
 
 
 ## Building from Source
 {: #building-from-source}
 
 Of course, you can install Ruby from source.
-[Download](/en/downloads/) and unpack a tarball, then just do this:
+[Download][download] and unpack a tarball, then just do this:
 
 {% highlight sh %}
 $ ./configure
@@ -294,6 +299,9 @@ $ sudo make install
 By default, this will install Ruby into `/usr/local`.
 To change, pass the `--prefix=DIR` option to the `./configure` script.
 
+You can find more information about building from source in the [Ruby
+README file][readme].
+
 Using the third-party tools or package managers might be a better idea,
 though, because the installed Ruby won't be managed by any tools.
 
@@ -314,3 +322,7 @@ though, because the installed Ruby won't be managed by any tools.
 [freebsd-ruby]: https://wiki.freebsd.org/Ruby
 [freebsd-ports-collection]: https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html
 [homebrew]: http://brew.sh/
+[terminal]: https://en.wikipedia.org/wiki/List_of_terminal_emulators
+[download]: /en/downloads/
+[installers]: /en/documentation/installation/#installers
+[readme]: https://github.com/ruby/ruby#how-to-compile-and-install