docs(repo): pam feedback

docs/getting-started/3-rulesets.md

@@ -15,13 +15,13 @@ Spectral comes with two built-in rulesets:
 - `spectral:oas` - [OpenAPI v2/v3 rules](./4-openapi.md)
 - `spectral:asyncapi` - [AsyncAPI v2 rules](./5-asyncapi.md)
 
-To create a ruleset that extends both rulesets, in your terminal run:
+To create a ruleset that extends both rulesets, open your terminal and run:
 
 ```bash
 echo 'extends: ["spectral:oas", "spectral:asyncapi"]' > .spectral.yaml
 ```
 
-The newly created ruleset file can then be used to lint any OpenAPI v2/v3 or AsyncAPI descriptions by using the `spectral lint` command:
+The newly created ruleset file can then be used to lint any OpenAPI v2/v3 or AsyncAPI descriptions using the `spectral lint` command:
 
 ```bash
 spectral lint myapifile.yaml
@@ -48,8 +48,8 @@ The example above is a rule that can be used to validate an OpenAPI description.
 
 Breaking down each part of the rule:
 
-- `description` and `message` will help users quickly understand what the goal of the rule is
-- `severity` will help define the importance of following the rule
+- `description` and `message` help users quickly understand what the goal of the rule is
+- `severity` help define the importance of following the rule
 - The `given` keyword tells Spectral what part of the JSON or YAML file to target by using [JSONPath](http://jsonpath.com/) (Spectral uses [JSONPath Plus](https://www.npmjs.com/package/jsonpath-plus)).
 - The `then` property includes the `function` type and options that tells Spectral how to apply the function to the JSON or YAML file, and make sure that the rule is being followed or not. Spectral has a set of [built-in functions](../reference/functions.md) such as `truthy` or `pattern`, which can be used to power rules.
 

docs/guides/4-custom-rulesets.md

@@ -10,10 +10,10 @@ There are five properties that can be used at the root level of a ruleset:
 
 - `rules` (required): An array of rules. See [Rules](./4a-rules.md) for more details.
 - `extends` (optional): A reference to other rulesets. Used to extend and customize existing rulesets. See [Extends](./4b-extends.md) for more details.
-- `formats` (optional): The format that the ruleset should apply to. For example `oas3` for any OpenAPI v3.x descriptions. Can be applied at the ruleset and/or rule level. See [Formats](#formats) for more details.
+- `formats` (optional): The format that the ruleset should apply to. For example, `oas3` for any OpenAPI v3.x descriptions. Can be applied at the ruleset and/or rule level. See [Formats](#formats) for more details.
 - `documentationUrl` (optional): A URL that contains more information about the ruleset and rules in it. Can help provide users more context on why the ruleset exists and how it should be used. See [Documentation URL](#documentation-url) for more details.
 - `parserOptions` (optional): Can be used to tune the severity of duplicate keys or invalid values in your ruleset. See [Parsing Options](#parsing-options) for more details.
-- `aliases` (optional): An array of key-value pairs that can be used to define commonly used JSONPath expressions, to be reused across a ruleset. See [Aliases](./4c-aliases.md) for more details.
+- `aliases` (optional): An array of key-value pairs that can be used to define commonly used JSONPath expressions to be reused across a ruleset. See [Aliases](./4c-aliases.md) for more details.
 - `overrides` (optional): Can be used to customize which formats, files, or parts of files, that a ruleset should be applied to. See [Overrides](./4d-overrides.md) for more details.
 
 Rules are the most important part of a ruleset. For more details on rules and its properties, see [Rules](./4a-rules.md).
@@ -41,26 +41,7 @@ Formats are an optional way to specify which API description formats a rule, or
 - `json-schema-2019-09` (`$schema` says this is JSON Schema 2019-09)
 - `json-schema-2020-12` (`$schema` says this is JSON Schema 2020-12)
 
-Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, the `formats` key is here to help.
-
-```yaml
-rules:
-  oas3-api-servers:
-    description: "OpenAPI `servers` must be present and non-empty array."
-    formats: ["oas3"]
-    given: "$"
-    then:
-      field: servers
-      function: schema
-      functionOptions:
-        schema:
-          items:
-            type: object
-          minItems: 1
-          type: array
-```
-
-Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats.
+Specifying the format is optional, so you can ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, use the `formats` key.
 
 Formats can be specified at the ruleset level:
 
@@ -140,7 +121,7 @@ rules:
 
 <!-- TODO: expand on this topic -->
 
-If you do not care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using the `parserOptions` setting.
+If you don't care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using the `parserOptions` setting.
 
 ```yaml
 extends: spectral:oas

docs/guides/4a-rules.md

@@ -24,7 +24,7 @@ Rules can have the following properties:
 - `given` (required): The part of the document the rule should be applied to. Uses the [JSONPath](https://goessner.net/articles/JsonPath/index.html) syntax.
 - `then` (required): Describes which function should be applied to the `given` part of the document. Can be used with a [core function](../reference/functions.md) or [custom function](./5-custom-functions.md).
 - `description` (optional): A short description of the rule.
-- `message` (optional): A message that will be displayed in the `spectral lint` output. Can be customized to use placeholder values that are evaluated at runtime, such as `{{description}}` or `{{error}}`.
+- `message` (optional): A message that's displayed in the `spectral lint` output. Can be customized to use placeholder values that are evaluated at runtime, such as `{{description}}` or `{{error}}`.
 - `severity` (optional): The severity of the rule. Used to differentiate between rules that must be followed (`error`) and warnings or hints. Default value is `warn`.
 - `formats` (optional): The format that the rule should apply to. For example `oas3` for any OpenAPI v3.x descriptions. Can be applied at the ruleset and/or rule level. See [Formats](./4-custom-rulesets.md#formats) for more details.
 - `recommended` (optional): Recommended is a property that is used when extending a ruleset, where users can define if they would like to enforce all rules (`recommended` set to `true` and `false`) or only recommended rules (`recommended` set to `true`). Recommended can be used to help slowly roll out a ruleset across API landscapes with a lot of legacy APIs. Default value is `true`. See [Recommended](./4e-recommended.md) for more details.
@@ -34,9 +34,9 @@ Let's look at all the properties that can be used for a rule.
 
 ### Given
 
-The `given` property is conceptually quite like a selector in CSS, in that it picks the part of the document to apply rules to.
+The `given` property is conceptually quite like a selector in CSS, in that it indicates the part of the document to apply rules to.
 
-It has a specific syntax known as [JSONPath](https://goessner.net/articles/JsonPath/index.html), which if you are familiar with XPath is quite similar. JSONPath is not yet a standard (it [will be](https://tools.ietf.org/html/draft-normington-jsonpath-00) someday), and has a few competing implementations. Spectral uses [nimma](https://www.npmjs.com/package/nimma) as its main implementation, and sometimes resorts to [jsonpath-plus](https://www.npmjs.com/package/jsonpath-plus) to ensure a good backwards-compatibility.
+It has a specific syntax known as [JSONPath](https://goessner.net/articles/JsonPath/index.html), which if you are familiar with XPath is quite similar. JSONPath is not yet a standard (it [will be](https://tools.ietf.org/html/draft-normington-jsonpath-00) someday), and has a few competing implementations. Spectral uses [nimma](https://www.npmjs.com/package/nimma) as its main implementation, and sometimes resorts to [jsonpath-plus](https://www.npmjs.com/package/jsonpath-plus) to ensure good backwards-compatibility.
 Both of them support all the main JSONPath functionality and a little bit more, but this syntax may differ slightly from other JSONPath implementations.
 
 Your `given` value can be a string containing any valid JSONPath expression, or an array of expressions to apply a rule to multiple parts of a document.
@@ -56,7 +56,7 @@ then:
   function: truthy
 ```
 
-The `field` keyword is optional and is used to apply the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSONPath. The value can also be `@key` to apply the rule to the keys of an object.
+The `field` keyword is optional and is used to apply the function to a specific property in an object. If omitted, the function will be applied to the entire target of the `given` JSONPath. The value can also be `@key` to apply the rule to the keys of an object.
 
 ```yaml
 given: "$.responses"
@@ -95,7 +95,7 @@ contact-properties:
 
 ### Message
 
-To help you create meaningful messages for results, Spectral comes with a couple of placeholders that are evaluated at runtime.
+To help you create meaningful messages for results, Spectral comes with placeholders that are evaluated at runtime.
 
 - `{{error}}` - the error returned by function
 - `{{description}}` - the description set on the rule
@@ -121,20 +121,13 @@ message: "{{path}} cannot point at remote reference"
 
 ### Severity
 
-The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`.
+The `severity` keyword is optional and can be `error`, `warn`, `info`, `hint`, or `off`.
 
 The default value is `warn`.
 
 ### Resolved
 
-By default, Spectral processes each rule on a "resolved" document (a file where
-all `$ref` JSON Schema references have been replaced with the objects they point
-to). While this is typically the desired behavior, there are some use cases
-where you may need to run a rule on the "raw" un-resolved document.
-
-For example, if you want to enforce conventions on the folder structure used for
-[splitting up
-documents](https://blog.stoplight.io/keeping-openapi-dry-and-portable?utm_medium=spectral&utm_source=github&utm_campaign=docs).
+By default, Spectral processes each rule on a "resolved" document (a file where all `$ref` JSON Schema references have been replaced with the objects they point to). While this is typically the desired behavior, there are some use cases where you may need to run a rule on the "raw" un-resolved document (for example, if you want to enforce conventions on the folder structure used for [splitting up documents](https://blog.stoplight.io/keeping-openapi-dry-and-portable?utm_medium=spectral&utm_source=github&utm_campaign=docs)).
 
 If your rule needs to access the raw `$ref` reference values, you can set `resolved: false` to allow the rule to receive the raw un-resolved version of the document. Otherwise `resolved: true` is the default.
 

docs/guides/4b-extends.md

@@ -15,7 +15,7 @@ extends:
   - 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).
+The `extends` keyword can be combined with extra rules to extend and override rulesets. Learn more about that in [custom rulesets](../guides/4-custom-rulesets.md).
 
 ## Modify Rules
 
@@ -34,7 +34,7 @@ rules:
 
 This provides a new description, but anything can be changed.
 
-If you're just looking to change the severity of the rule, there is a handy shortcut.
+If you're just looking to change the severity of the rule, there's a handy shortcut.
 
 ## Change Rule Severity
 
@@ -46,4 +46,4 @@ rules:
   operation-success-response: warn
 ```
 
-Available severity levels are `error`, `warn`, `info`, `hint`, and `off`.
+See [Severity](./4a-rules.md#severity) for more details.

docs/guides/4c-aliases.md

@@ -1,7 +1,8 @@
 ## Aliases
 
 Targeting certain parts of an OpenAPI spec is powerful but it can become cumbersome to write and repeat complex JSONPath expressions across various rules.
-Define aliases for commonly used JSONPath expressions on a global level which can then be reused across the ruleset.
+
+Define aliases for commonly used JSONPath expressions on a global level and then reuse them across the ruleset.
 
 Aliases can be defined in an array of key-value pairs at the root level of the ruleset, or alternatively, within an override.
 

docs/guides/4d-overrides.md

@@ -1,6 +1,6 @@
 ## Overrides
 
-Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or change parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules.
+Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or change parts of a rule. Overrides are the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules.
 
 Overrides can be used to apply rulesets on:
 
@@ -58,7 +58,7 @@ In the event of multiple matches, the order of definition takes place, with the
 
 ### Caveats
 
-Please bear in mind that overrides are only applied to the _root_ documents. If your documents have any external dependencies, i.e. $refs, the overrides won't apply.
+Overrides are only applied to the _root_ documents. If your documents have any external dependencies, i.e. $refs, the overrides won't apply.
 
 **Example:**
 

docs/guides/4e-recommended.md

@@ -14,7 +14,7 @@ Far more rules exist than just the recommended ones, there are various other rul
 extends: [[spectral:oas, all]]
 ```
 
-You can do this with your rulesets, and slide new rules in as not recommended for a while so that only the most interested active API designers/developers get them at first, then eventually roll them out to everyone if they are well received.
+You can do this with your rulesets, and initially set new rules as "not recommended" so that the most interested active API designers/developers use them at first. Then, eventually roll them out to everyone if they are well received.
 
 ### Disabling Rules
 
@@ -26,16 +26,16 @@ rules:
   operation-operationId-unique: off
 ```
 
-The example above will run all of the rules defined in the `spectral:oas` ruleset (rather than the default behavior that runs only the recommended ones), with one exception - we turned `operation-operationId-unique` off.
+The example above runs all of the rules defined in the `spectral:oas` ruleset (rather than the default behavior that runs only the recommended ones), with one exception; `operation-operationId-unique` is set to off.
 
 ### Enabling Rules
 
-Sometimes you might want to apply a limited number of rules from another ruleset. To do this, use the `extends` property with `off` as the second argument. This will avoid running any rules from the extended ruleset as they will all be disabled. Then you can pick and choose which rules you would like to enable.
+Sometimes you might want to apply a limited number of rules from another ruleset. To do this, use the `extends` property with `off` as the second argument. This avoids running any rules from the extended ruleset as they will all be disabled. Then you can pick and choose which rules you would like to enable.
 
 ```yaml
 extends: [[spectral:oas, off]]
 rules:
   operation-operationId-unique: true
 ```
 
-The example above will only run the rule `operation-operationId-unique` that we enabled since we passed `off` to disable all rules by default when extending the `spectral:oas` ruleset.
+The example above only runs the rule `operation-operationId-unique` that we enabled since we passed `off` to disable all rules by default when extending the `spectral:oas` ruleset.

docs/guides/4f-js-rulesets.md

@@ -2,7 +2,11 @@
 
 Spectral v6.0 added support for a JavaScript ruleset format, similar to the JSON and YAML formats.
 
-This has a few benefits: it lets you explicitly load formats or rulesets to get control over versioning, you can load common functions from popular JS libraries, and in general feels a lot more welcoming to developers experienced with JavaScript, especially when it comes to working with custom functions.
+This has a few benefits:
+
+- It lets you explicitly load formats or rulesets to get control over versioning.
+- You can load common functions from popular JS libraries.
+- It feels a lot more welcoming to developers experienced with JavaScript, especially when it comes to working with custom functions.
 
 **Example**
 
@@ -20,15 +24,15 @@ npm install --save @stoplight/spectral-functions
 npm install --save @stoplight/spectral-formats
 ```
 
-Installing these packages is not required for creating a JavaScript ruleset, but we'll use them in our example to create some common rules used with Spectral and to target a specific OpenAPI format.
+Installing these packages is not required for creating a JavaScript ruleset, but you'll use them in the example to create some common rules used with Spectral and to target a specific OpenAPI format.
 
-Next, let's create a JavaScript file to hold our ruleset:
+Next, create a JavaScript file to hold your ruleset:
 
 ```
 touch spectral.js
 ```
 
-And inside the file, let's create a couple rules:
+Inside the file, create a couple of rules:
 
 ```js
 import { truthy, undefined as pattern, schema } from "@stoplight/spectral-functions";
@@ -92,7 +96,7 @@ export default {
 };
 ```
 
-For those of you using custom functions, the keywords `functions` & `functionOptions` have been removed, as they were designed to help Spectral find your functions. Now functions are passed as a variable, instead of using a string that contains the name like the JSON/YAML formats.
+If you use custom functions, the keywords `functions` and `functionOptions` have been removed, as they were designed to help Spectral find your functions. Now functions are passed as a variable, instead of using a string that contains the name like the JSON/YAML formats.
 
 This code example should look fairly familiar for anyone who has used the JSON or YAML formats. The next steps for using this ruleset would be publishing it as an npm package, and then installing that package as part of your API project and referencing in your Spectral ruleset as: