[DOC] Improve building_ruby.md

1 files changed, 45 insertions, 10 deletions

diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md
index ace5fbed37..4fbb4bd2cc 100644
--- a/doc/contributing/building_ruby.md
+++ b/doc/contributing/building_ruby.md
@@ -10,7 +10,7 @@
     * gperf - 3.0.3 or later
     * ruby - 2.7 or later
 
-2. Install optional, recommended dependencies:
+1. Install optional, recommended dependencies:
 
     * OpenSSL/LibreSSL
     * readline/editline (libedit)
@@ -20,29 +20,64 @@
     * libexecinfo (FreeBSD)
     * rustc - 1.58.1 or later (if you wish to build [YJIT](/doc/yjit/yjit.md))
 
-3. Checkout the CRuby source code:
+1. Checkout the CRuby source code:
 
     ```
     git clone https://github.com/ruby/ruby.git
     ```
 
-4. Generate the configuration files and build. It's generally advisable to use a build directory:
+1. Generate the configure file:
 
     ```
     ./autogen.sh
-    mkdir build && cd build # it's good practice to build outside of source dir
-    mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
+    ```
+
+1. Create a `build` directory outside of the source directory:
+
+    ```
+    mkdir build && cd build
+    ```
+
+    While it's not necessary to build in a separate directory, it's good practice to do so.
+
+1. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory:
+
+    ```
+    mkdir ~/.rubies
+    ```
+
+1. Run configure:
+
+    ```
     ../configure --prefix="${HOME}/.rubies/ruby-master"
-    make install
     ```
 
-5. Optional: If you are frequently building Ruby, disabling documentation will reduce the time it takes to `make`:
+    - If you are frequently building Ruby, add the `--disable-install-doc` flag to not build documentation which will speed up the build process.
 
-    ``` shell
-    ../configure --prefix="${HOME}/.rubies/ruby-master" --disable-install-doc
+1. Build Ruby:
+
+    ```
+    make install
     ```
 
-6. [Run tests](testing_ruby.md) to confirm your build succeeded
+    - If you're on macOS and installed \OpenSSL through Homebrew, you may encounter failure to build \OpenSSL that look like this:
+
+        ```
+        openssl:
+            Could not be configured. It will not be installed.
+            ruby/ext/openssl/extconf.rb: OpenSSL library could not be found. You might want to use --with-openssl-dir=<dir> option to specify the prefix where OpenSSL is installed.
+            Check ext/openssl/mkmf.log for more details.
+        ```
+
+        Running the following command may solve the issue:
+
+        ```
+        brew link openssl --force
+        ```
+
+        Remember to delete your `build` directory and start again from the configure step.
+
+6. [Run tests](testing_ruby.md) to confirm your build succeeded.
 
 ### Unexplainable Build Errors