1 files changed, 36 insertions, 6 deletions
diff --git a/spec/README.md b/spec/README.md
index c67aedbb80..6a88c06e09 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -1,14 +1,23 @@
 # spec/bundler
 
-spec/bundler is rspec examples for bundler library(lib/bundler.rb, lib/bundler/*).
+spec/bundler is rspec examples for bundler library (`lib/bundler.rb`, `lib/bundler/*`).
 
 ## Running spec/bundler
 
 To run rspec for bundler:
+
 ```bash
 make test-bundler
 ```
 
+or run rspec with parallel execution:
+
+```bash
+make test-bundler-parallel
+```
+
+If you specify `BUNDLER_SPECS=foo/bar_spec.rb` then only `spec/bundler/foo/bar_spec.rb` will be run.
+
 # spec/ruby
 
 ruby/spec (https://github.com/ruby/spec/) is
@@ -37,6 +46,7 @@ which change behavior or are removed. This is necessary for other Ruby implement
 to still be able to run the specs and contribute new specs.
 
 For example, change:
+
 ```ruby
 describe "Some spec" do
   it "some example" do
@@ -44,7 +54,9 @@ describe "Some spec" do
   end
 end
 ```
+
 to:
+
 ```ruby
 describe "Some spec" do
   ruby_version_is ""..."2.7" do
@@ -64,7 +76,8 @@ end
 See `spec/ruby/CONTRIBUTING.md` for more documentation about guards.
 
 To verify specs are compatible with older Ruby versions:
-```
+
+```bash
 cd spec/ruby
 $RUBY_MANAGER use 2.4.9
 ../mspec/bin/mspec -j
@@ -73,28 +86,33 @@ $RUBY_MANAGER use 2.4.9
 ## Running ruby/spec
 
 To run all specs:
+
 ```bash
 make test-spec
 ```
 
-Extra arguments can be added via `MSPECOPT`.
+Extra arguments can be added via `SPECOPTS`.
 For instance, to show the help:
+
 ```bash
-make test-spec MSPECOPT=-h
+make test-spec SPECOPTS=-h
 ```
 
 You can also run the specs in parallel, which is currently experimental.
 It takes around 10s instead of 60s on a quad-core laptop.
+
 ```bash
-make test-spec MSPECOPT=-j
+make test-spec SPECOPTS=-j
 ```
 
 To run a specific test, add its path to the command:
+
 ```bash
-make test-spec MSPECOPT=spec/ruby/language/for_spec.rb
+make test-spec SPECOPTS=spec/ruby/language/for_spec.rb
 ```
 
 If ruby trunk is your current `ruby` in `$PATH`, you can also run `mspec` directly:
+
 ```bash
 # change ruby to trunk
 ruby -v # => trunk
@@ -128,3 +146,15 @@ end
 ```
 
 For more details, see `spec/ruby/CONTRIBUTING.md`.
+
+# spec/syntax_suggest
+
+## Running spec/syntax_suggest
+
+To run rspec for syntax_suggest:
+
+```bash
+make test-syntax-suggest
+```
+
+If you specify `SYNTAX_SUGGEST_SPECS=foo/bar_spec.rb` then only `spec/syntax_suggest/foo/bar_spec.rb` will be run.