diff --git a/docs/getting-started/3-rulesets.md b/docs/getting-started/3-rulesets.md
index b4bf91d1a..8361550ed 100644
--- a/docs/getting-started/3-rulesets.md
+++ b/docs/getting-started/3-rulesets.md
@@ -66,7 +66,7 @@ Extends can reference any [distributed ruleset](../guides/7-sharing-rulesets.md)
 extends:
   - ./config/spectral.json
   - https://example.org/api/style.yaml
-  - some-npm-module
+  - some-npm-module # note that this would be treated as any other npm package, therefore it has to be placed under node_modules and have a valid package.json.
 ```
 
 The `extends` keyword can be combined with extra rules in order to extend and override rulesets. Learn more about that in [custom rulesets](../guides/4-custom-rulesets.md).
diff --git a/docs/guides/3-javascript.md b/docs/guides/3-javascript.md
index d60ac9d13..d96ed03f6 100644
--- a/docs/guides/3-javascript.md
+++ b/docs/guides/3-javascript.md
@@ -53,22 +53,62 @@ Find out how to add formats, rules and functions below.
 
 ## Loading Rulesets
 
-Spectral comes with some rulesets that are very specific to OpenAPI v2/v3, and they can be loaded using `Spectral.loadRuleset()`.
+Spectral comes with some rulesets that are very specific to OpenAPI v2/v3, and they can be set using `Spectral.setRuleset()`.
 
 ```js
 const { Spectral } = require("@stoplight/spectral-core");
-const ruleset = require("./my-ruleset"); // if you use a YAML/JSON ruleset, make sure to use @stoplight/spectral-ruleset-migrator first.
-
-const myOpenApiDocument = `
-openapi: 3.0.0
-# here goes the rest of document
-`;
+const ruleset = require("./my-ruleset"); // this works only for JS ruleset, look at the section below to learn how to load a YAML/JSON ruleset
 
 const spectral = new Spectral();
 spectral.setRuleset(ruleset);
-spectral.run(myOpenApiDocument).then(results => {
-  console.log("here are the results", results);
-});
+// lint
+```
+
+### Loading YAML/JSON rulesets
+
+#### Node.js
+
+```js
+const path = require("path");
+const fs = require("fs");
+
+const { Spectral } = require("@stoplight/spectral-core");
+const { fetch } = require("@stoplight/spectral-runtime"); // can also use isomorphic-fetch, etc.. If you ruleset does not reference any external assets, you can provide some stub instead.
+const { bundleAndLoadRuleset } = require("@stoplight/spectral-ruleset-bundler/with-loader");
+// const { commonjs } = require("@stoplight/spectral-ruleset-bundler/plugins/commonjs"); needed if you want to use CommonJS
+
+const rulesetFilepath = path.join(__dirname, ".spectral.yaml");
+
+const spectral = new Spectral();
+s.setRuleset(await bundleAndLoadRuleset(rulesetFilepath, { fs, fetch }));
+// or, if you use module.exports (CommonJS) s.setRuleset(await bundleAndLoadRuleset(rulesetFilepath, { fs, fetch }), [commonjs()]);
+```
+
+#### Browser
+
+```js
+const { Spectral } = require("@stoplight/spectral-core");
+const { bundleAndLoadRuleset } = require("@stoplight/spectral-ruleset-bundler/with-loader");
+// const { commonjs } = require("@stoplight/spectral-ruleset-bundler/plugins/commonjs"); needed if you want to use CommonJS
+
+const myRuleset = `extends: spectral:oas
+rules: {}`;
+
+const fs = {
+  promises: {
+    async readFile(filepath) {
+      if (filepath === "/.spectral.yaml") {
+        return myRuleset;
+      }
+
+      throw new Error(`Could not read ${filepath}`);
+    },
+  },
+};
+
+const spectral = new Spectral();
+s.setRuleset(await bundleAndLoadRuleset("/.spectral.yaml", { fs, fetch }));
+// or, if you use module.exports (CommonJS) s.setRuleset(await bundleAndLoadRuleset(rulesetFilepath, { fs, fetch }), [commonjs()]);
 ```
 
 ## Advanced
diff --git a/docs/guides/7-sharing-rulesets.md b/docs/guides/7-sharing-rulesets.md
index b7659c63a..f749700ec 100644
--- a/docs/guides/7-sharing-rulesets.md
+++ b/docs/guides/7-sharing-rulesets.md
@@ -14,7 +14,7 @@ Or mix and match!
 extends:
   - ./config/spectral.json
   - https://example.org/api/style.yaml
-  - some-npm-module
+  - some-npm-module # note that this would be treated as any other npm package, therefore it has to live under node_modules, and have a valid package.json.
 ```
 
 There are various pros and cons to each approach, so see what is right for you.
@@ -109,7 +109,7 @@ module.exports = function (targetVal, { min }) {
 };
 ```
 
-Developers wanting to pull in your ruleset can just reference the module name in `extends`:
+Developers wanting to pull in your ruleset can just install the package using yarn or npm and reference the module name in `extends`:
 
 ```yaml
 extends:
@@ -126,7 +126,7 @@ Pegging a ruleset on given version is possible through a `package.json`:
 }
 ```
 
-Or through the use of CDNs for NPM repository, such as [unpkg.com](https://unpkg.com/):
+If you Spectral in a browser or don't want to install the package, you can also reference that package through the use of CDNs for NPM repository, such as [unpkg.com](https://unpkg.com/):
 
 ```yaml
 extends: