revise intro on Install page; provide clearer recommendations for which installation method to use

2 files changed, 13 insertions, 8 deletions

diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc
index 10ec8d95..68d9deda 100644
--- a/docs/modules/install/pages/index.adoc
+++ b/docs/modules/install/pages/index.adoc
@@ -1,19 +1,24 @@
 = Install and Update
 
-To simplify installation, Asciidoctor is packaged and distributed as a {url-rubygems}/asciidoctor[RubyGem to the package repository at RubyGems.org^].
+To simplify installation, Asciidoctor is packaged and published as a {url-rubygems}/asciidoctor[RubyGem to the package repository at RubyGems.org^].
 It's also distributed as a package for popular Linux distributions and macOS.
-In addition to running on Ruby, Asciidoctor can be executed on a JVM using xref:asciidoctorj::index.adoc[AsciidoctorJ] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
+
+TIP: In addition to running on Ruby, Asciidoctor can be executed on a JVM using xref:asciidoctorj::index.adoc[AsciidoctorJ] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
 
 == Installation methods
 
 Asciidoctor can be installed using:
 
-* package managers for popular Linux distributions,
+* Bundler,
+* the package manager for popular Linux distributions,
 * Homebrew or MacPorts for macOS,
-* the `gem install` command (recommended for Windows users or if you'll be installing additional gems),
-* the Asciidoctor Docker image, or
-* Bundler.
+* the `gem install` command (recommended for Windows users), or
+* the Asciidoctor Docker image
 
-The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+Bundler is the preferred method of installation as it keeps the gems scoped to your project or workspace.
+However, it does not make the `asciidoctor` command globally available in your terminal.
+That's when a package manager is more appropriate.
+The benefit of using your operating system's package manager to install the gem is that it adds the `asciidoctor` command to your PATH and it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+On the other hand, if you're familiar with Docker, using the Asciidoctor Docker image gives you the best isolation from your system.
 
 You should use the same method to update Asciidoctor as you use to install it.
diff --git a/docs/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc
index 9b7ce7c1..140bf469 100644
--- a/docs/modules/install/pages/supported-platforms.adoc
+++ b/docs/modules/install/pages/supported-platforms.adoc
@@ -1,7 +1,7 @@
 = Supported Platforms and System Requirements
 :navtitle: Supported Platforms
 
-Asciidoctor operates on Linux, macOS and Windows and requires one of the supported Ruby implementations listed in the next section.
+Asciidoctor operates on Linux, macOS, and Windows and requires one of the supported Ruby implementations listed in the next section.
 
 Our general policy is to align Asciidoctor's support of a platform version with the upstream project's lifecycle schedule for that version.
 When a platform version reaches the end of active support by its maintainers or its end of life--which ever comes first--Asciidoctor no longer supports it.