diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md
index ae477e23c1..f11b6e2f2a 100644
--- a/guides/source/active_storage_overview.md
+++ b/guides/source/active_storage_overview.md
@@ -37,7 +37,7 @@ arbitrary files.
 Various features of Active Storage depend on third-party software which Rails 
 will not install, and must be installed separately:
 
-* [libvips](https://github.com/libvips/libvips) or [ImageMagick](https://imagemagick.org/index.php) v8.6+ for image analysis and transformations
+* [libvips](https://github.com/libvips/libvips) v8.6+ or [ImageMagick](https://imagemagick.org/index.php) for image analysis and transformations
 * [ffmpeg](http://ffmpeg.org/) v3.4+ for video/audio analysis and video previews
 * [poppler](https://poppler.freedesktop.org/) or [muPDF](https://mupdf.com/) for PDF previews
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 55f7a2c451..a281d1e7dc 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -231,16 +231,22 @@ more meaningful preview images. Previously the first frame of the video would be
 and that caused problems if the video faded in from black. This change requires
 FFmpeg v3.4+.
 
-### ActiveStorage variant processor changed to :vips
+### Active Storage default variant processor changed to `:vips`
 
-Image transformation will now use libvips instead of ImageMagick. This will reduce
+For new apps, image transformation will use libvips instead of ImageMagick. This will reduce
 the time taken to generate variants as well as CPU and memory usage, improving response
 times in apps that rely on active storage to serve their images.
 
 The `:mini_magick` option is not being deprecated, so it is fine to keep using it.
 
-Migrating to libvips requires changing existing image transformation code to the
-`image_processing` macros, and replacing ImageMagick's options with libvips' options.
+To migrate an existing app to libvips, set:
+
+```ruby
+Rails.application.config.active_storage.variant_processor = :vips
+```
+
+You will then need to change existing image transformation code to the
+`image_processing` macros, and replace ImageMagick's options with libvips' options.
 
 #### Replace resize with resize_to_limit
 ```diff
@@ -248,7 +254,7 @@ Migrating to libvips requires changing existing image transformation code to the
 + variant(resize_to_limit: [100, nil])
 ```
 
-If you forget to do this, when you switch to vips you will see this error: `no implicit conversion to float from string`.
+If you don't do this, when you switch to vips you will see this error: `no implicit conversion to float from string`.
 
 #### Use an array when cropping
 ```diff
@@ -256,17 +262,20 @@ If you forget to do this, when you switch to vips you will see this error: `no i
 + variant(crop: [0, 0, 1920, 1080])
 ```
 
-If you forget to do this, when you switch to vips you will see this error: `unable to call crop: you supplied 2 arguments, but operation needs 5`.
+If you don't do this when migrating to vips, you will see the following error: `unable to call crop: you supplied 2 arguments, but operation needs 5`.
 
 #### Clamp your crop values:
+
 Vips is more strict than ImageMagick when it comes to cropping:
+
 1. It will not crop if `x` and/or `y` are negative values. e.g.: `[-10, -10, 100, 100]`
 2. It will not crop if position (`x` or `y`) plus crop dimension (`width`, `height`) is larger than the image. e.g.: a 125x125 image and a crop of `[50, 50, 100, 100]`
 
-If you forget to do this, when you switch to vips you will see this error: `extract_area: bad extract area`
+If you don't do this when migrating to vips, you will see the following error: `extract_area: bad extract area`
 
-#### Adjust the background color used in resize and pad
+#### Adjust the background color used for `resize_and_pad`
 Vips uses black as the default background color `resize_and_pad`, instead of white like ImageMagick. Fix that by using the `background` option:
+
 ```diff
 - variant(resize_and_pad: [300, 300])
 + variant(resize_and_pad: [300, 300, background: [255]])
@@ -274,6 +283,7 @@ Vips uses black as the default background color `resize_and_pad`, instead of whi
 
 #### Remove any EXIF based rotation
 Vips will auto rotate images using the EXIF value when processing variants. If you were storing rotation values from user uploaded photos to apply rotation with ImageMagick, you must stop doing that:
+
 ```diff
 - variant(format: :jpg, rotate: rotation_value)
 + variant(format: :jpg)
@@ -281,6 +291,7 @@ Vips will auto rotate images using the EXIF value when processing variants. If y
 
 #### Replace monochrome with colourspace
 Vips uses a different option to make monochrome images:
+
 ```diff
 - variant(monochrome: true)
 + variant(colourspace: "b-w")
@@ -288,24 +299,28 @@ Vips uses a different option to make monochrome images:
 
 #### Switch to libvips options for compressing images
 JPEG
+
 ```diff
 - variant(strip: true, quality: 80, interlace: "JPEG", sampling_factor: "4:2:0", colorspace: "sRGB")
 + variant(saver: { strip: true, quality: 80, interlace: true })
 ```
 
 PNG
+
 ```diff
 - variant(strip: true, quality: 75)
 + variant(saver: { strip: true, compression: 9 })
 ```
 
 WEBP
+
 ```diff
 - variant(strip: true, quality: 75, define: { webp: { lossless: false, alpha_quality: 85, thread_level: 1 } })
 + variant(saver: { strip: true, quality: 75, lossless: false, alpha_q: 85, reduction_effort: 6, smart_subsample: true })
 ```
 
 GIF
+
 ```diff
 - variant(layers: "Optimize")
 + variant(saver: { optimize_gif_frames: true, optimize_gif_transparency: true })
@@ -313,11 +328,12 @@ GIF
 
 #### Deploy to production
 Active Storage encodes into the url for the image the list of transformations that must be performed.
-If you app is caching these urls, your images will break after you deploy the new code to production.
+If your app is caching these urls, your images will break after you deploy the new code to production.
 Because of this you must manually invalidate your affected cache keys.
 
 For example, if you have something like this in a view:
-```rhtml
+
+```ruby
 <% @products.each do |product| %>
   <% cache product do %>
     <%= image_tag product.cover_photo.variant(resize: "200x") %>
@@ -326,7 +342,8 @@ For example, if you have something like this in a view:
 ```
 
 You can invalidate the cache either by touching the product, or changing the cache key:
-```rhtml
+
+```ruby
 <% @products.each do |product| %>
   <% cache ["v2", product] do %>
     <%= image_tag product.cover_photo.variant(resize_to_limit: [200, nill]) %>