docs(repo): pam feedback

README.md

@@ -70,17 +70,17 @@ spectral lint myapifile.yaml --ruleset myruleset.yaml
 
 Once you've had a look through the getting started material, some of these guides can help you become a power user.
 
-- [Different Workflows](https://meta.stoplight.io/docs/spectral/docs/guides/1-workflows.md) - When and where should you use Spectral? Editors, Git-hooks, Continuous Integration, GitHub Actions, wherever you like.
+- [Different Workflows](https://meta.stoplight.io/docs/spectral/docs/guides/1-workflows.md) - When and where should you use Spectral? Editors, Git hooks, continuous integration, GitHub Actions, wherever you like!
 - [Using the command-line interface](https://meta.stoplight.io/docs/spectral/docs/guides/2-cli.md) - Quickest way to get going with Spectral is in the CLI.
 - [Using the JavaScript API](https://meta.stoplight.io/docs/spectral/docs/guides/3-javascript.md) - Access the _raw power_ of Spectral via the JS, or hey, TypeScript if you want.
 - [Custom Rulesets](https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md) - Need something more than the core rulesets provide? Fancy building your own API Style Guide? Learn how to create a custom ruleset.
 - [Custom Functions](https://meta.stoplight.io/docs/spectral/docs/guides/5-custom-functions.md) - Handle more advanced rules, by writing a little JavaScript/TypeScript and calling it as a function.
 
 ## ℹ️ Support
 
-If you need help using Spectral or have any questions, please use [GitHub Discussions](https://github.com/stoplightio/spectral/discussions), or visit the [Stoplight Community Discord](https://discord.com/invite/stoplight). These communities are a great place to share your rulesets, or show off tools that use Spectral.
+If you need help using Spectral or have any questions, you can use [GitHub Discussions](https://github.com/stoplightio/spectral/discussions), or visit the [Stoplight Community Discord](https://discord.com/invite/stoplight). These communities are a great place to share your rulesets, or show off tools that use Spectral.
 
-If you have a bug or feature request, please [create an issue](https://github.com/stoplightio/spectral/issues).
+If you have a bug or feature request, [create an issue for it](https://github.com/stoplightio/spectral/issues).
 
 ## 🌎 Real-World Rulesets
 
@@ -131,6 +131,6 @@ Spectral is 100% free and open-source, under [Apache License 2.0](LICENSE).
 
 ## 🌲 Sponsor Spectral by Planting a Tree
 
-If you would like to thank Stoplight for creating Spectral, we ask that you [**buy the world a tree**][stoplight_forest].
+If you would like to thank Stoplight for creating Spectral, [**buy the world a tree**][stoplight_forest].
 
 [stoplight_forest]: https://ecologi.com/stoplightinc

docs/getting-started/1-concepts.md

@@ -10,10 +10,10 @@ To achieve this, Spectral has three key concepts:
 
 Spectral comes bundled with a [set of core functions](../reference/functions.md) and rulesets for working with [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md) that you can chose to use or extend, but Spectral is about far more than just checking your OpenAPI/AsyncAPI documents are valid.
 
-By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and several can be found on [API Stylebook](http://apistylebook.com/), but most of these rules could be automated with Spectral.
+By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and several can be found on [API Stylebook](http://apistylebook.com/), but most of these rules could be automated with Spectral. For example:
 
 - Paths must be `/kebab-case` ([more ideas for URL rules](https://blog.stoplight.io/consistent-api-urls-with-openapi-and-style-guides))
-- HTTP Basic isn't allowed at this company
+- HTTP Basic isn't allowed
 - Restrict the use of numeric integers in favor of UUID or any other ID pattern you choose
 - Enforce consistent hypermedia formats, like [JSON:API], or [another format](https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/).
 

docs/getting-started/2-installation.md

@@ -14,13 +14,13 @@ yarn global add @stoplight/spectral-cli
 
 ## Executable Binaries
 
-For users without Node.js and/or npm/Yarn, you can use the standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script:
+If you don't have Node.js and/or npm/Yarn, use the standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script:
 
 ```bash
 curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh | sh
 ```
 
-The binaries **don't autoupdate**, so you have to run the command again to install new versions.
+The binaries **don't autoupdate**, so you must run the command again to install new versions.
 
 ## Docker
 

docs/getting-started/3-rulesets.md

@@ -1,6 +1,6 @@
 # Create a Ruleset
 
-Rulesets are collections of rules written in JSON, YAML, or [JavaScript](../guides/4-custom-rulesets.md#alternative-js-ruleset-format), which can be used to power powerful linting of other JSON or YAML files, such as OpenAPI or AsyncAPI descriptions.
+Rulesets are collections of rules written in JSON, YAML, or [JavaScript](../guides/4-custom-rulesets.md#alternative-js-ruleset-format). Rulesets provide powerful linting of other JSON or YAML files, such as OpenAPI or AsyncAPI descriptions.
 
 Ruleset files are often named `.spectral.yaml`, but that's not a requirement.
 
@@ -29,7 +29,7 @@ spectral lint myapifile.yaml
 
 ## Write Your First Rule
 
-Here's what a ruleset with a single rule looks like:
+Here's an example of a ruleset with a single rule:
 
 ```yaml
 rules:
@@ -44,7 +44,7 @@ rules:
         match: "^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
 ```
 
-The example above is a rule that can be used to validate an OpenAPI description. It looks at all the `paths` properties to make sure they're kebab-case (lower-case and separated with hyphens).
+The example rule validates an OpenAPI description by ensuring the `paths` properties uses kebab-case (lower-case and separated with hyphens).
 
 Breaking down each part of the rule:
 

docs/guides/1-workflows.md

@@ -25,7 +25,7 @@ If the API description documents live in some other format, such as comments or
 swagger generate spec -o ./tmp/openapi.json && spectral lint ./tmp/openapi.json
 ```
 
-After you've written your code and your API is already in production, if Spectral points anything out with your API description, figuring out what to do next could be troublesome.
+After your API is in production, changing problems that Spectral finds could be troublesome.
 
 For example, if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/).
 

docs/guides/2-cli.md

@@ -62,11 +62,11 @@ Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or exte
 
 ## Error Results
 
-Spectral has a few different error severities: `error`, `warn`, `info`, and `hint`, and they're in "order" from highest to lowest. By default, all results are shown regardless of severity, but since v5.0, only the presence of errors causes a failure status code of 1. Seeing results and getting a failure code for it are now two different things.
+Spectral has a few different error severities: `error`, `warn`, `info`, and `hint`, and they're in order from highest to lowest. By default, all results are shown regardless of severity, but since v5.0, only the presence of errors causes a failure status code of 1. Seeing results and getting a failure code for it are now two different things.
 
-The default behavior can be modified with the `--fail-severity=` option. Setting fail severity to `--fail-severity=info` would return a failure status code of 1 for any info results or higher. Using `--fail-severity=warn` causes a failure status code for errors or warnings.
+The default behavior can be modified with the `--fail-severity=` option. Setting fail severity to `--fail-severity=info` returns a failure status code of 1 for any info results or higher. Using `--fail-severity=warn` causes a failure status code for errors or warnings.
 
-Changing the fail severity wont' affect output. To change the results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This strips out any results which are below the specified fail severity.
+Changing the fail severity wont' affect output. To change the results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This removes any results which are below the specified fail severity.
 
 ## Proxying
 
@@ -76,7 +76,7 @@ To have requests made from Spectral be proxied through a server, you'd need to s
 
 ## Custom \$ref Resolving
 
-If you want to customize \$ref resolving, you can use the `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
+To customize $ref resolving, use the `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
 
 ### Example
 

docs/guides/4a-rules.md

@@ -27,7 +27,7 @@ Rules can have the following properties:
 - `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's 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.
+- `recommended` (optional): Use `recommended` when extending a ruleset so users can enforce all rules (`recommended` set to `false`) or only recommended rules (`recommended` set to `true`). Recommended can be used to 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.
 - `resolved` (optional): Used to apply a rule to a document that's not "resolved," where `$ref` JSON Schema references haven't been replaced with the objects they point to.
 
 Let's look at all the properties that can be used for a rule.
@@ -36,9 +36,7 @@ Let's look at all the properties that can be used for a rule.
 
 The `given` property is conceptually similar to 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 isn't yet a standard (it [should 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 bit more, but this syntax may differ slightly from other JSONPath implementations.
+`given` has a specific syntax known as [JSONPath](https://goessner.net/articles/JsonPath/index.html), which is similar to XPath. JSONPath isn't yet a standard (it [should 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 backwards-compatibility. Both support all the main JSONPath functionality and a 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.
 You can also consume your [aliases](4c-aliases.md) here if you have some defined.

docs/guides/4e-recommended.md

@@ -8,7 +8,7 @@ You can try this out with the core OpenAPI ruleset. If you simply extend the rul
 extends: [[spectral:oas, recommended]]
 ```
 
-Far more rules exist than just the recommended ones, there are other rules which can help you create high-quality OpenAPI descriptions.
+Far more rules exist than just the recommended ones. There are other rules to help you create high-quality OpenAPI descriptions.
 
 ```yaml
 extends: [[spectral:oas, all]]

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

@@ -98,7 +98,7 @@ export default {
 
 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 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:
+Next, publish the ruleset as an npm package, and then install that package as part of your API project and reference it in your Spectral ruleset as:
 
 ```
 extends: ["@your-js-ruleset"]

docs/guides/5-custom-functions.md

@@ -267,9 +267,7 @@ export default createRulesetFunction(
 );
 ```
 
-It's worth keeping in mind, Spectral attempts to deduplicate messages when they have the same `code` and target the same `path`.
-
-As such, if your custom function returns more than one result, you should specify a different `path` for each result.
+Spectral attempts to deduplicate messages when they have the same `code` and target the same `path`. As such, if your custom function returns more than one result, you should specify a different `path` for each result.
 
 ## Referencing Core Functions
 
@@ -299,8 +297,8 @@ As of Spectral 5.4.0, custom functions can also be asynchronous.
 
 <!-- theme: warning -->
 
-> Ideally linting should always be deterministic, which means if it's run 10 times it should return the same results 10 times. To ensure this is the case, please refrain from introducing any logic that's prone to non-deterministic behavior. Examples of this might be contacting an external service you have no control over, or that's unstable, or that changes the way it responds over time.
-> While it may seem tempting to have a function that does so, the primary use case is to support libraries that makes async fs calls or exchange information, such as obtaining a dictionary file, with a locally running server, etc.
+> Ideally linting should always be deterministic, which means if it's run 10 times it should return the same results 10 times. To ensure this is the case, refrain from introducing any logic that's prone to non-deterministic behavior. Examples of this might be contacting an external service you have no control over, or that's unstable, or that changes the way it responds over time.
+> While it may seem tempting to have a function that does so, the primary use case is to support libraries that makes `async fs` calls or exchange information, such as obtaining a dictionary file, with a locally running server, etc.
 
 **functions/dictionary.js**
 
@@ -359,7 +357,7 @@ rules:
 
 ## Security Concerns
 
-Please, do keep in mind that for the time being, the code **isn't** executed in a sandbox environment, so be careful when including external rulesets.
+Keep in mind that for the time being, the code **isn't** executed in a sandbox environment, so be careful when including external rulesets.
 
 This indicates that almost any arbitrary code can be executed.
 

docs/guides/8-continuous-integration.md

@@ -2,7 +2,7 @@
 
 Spectral CLI can be run anywhere that npm packages can be installed and run via CLI, which these days is pretty much any CI solution going.
 
-Here are some examples of Spectral in CI solutions to give you an idea.
+Here are some examples of Spectral in CI solutions.
 
 ## CircleCI
 
@@ -41,7 +41,7 @@ Make sure to change `openapi.yaml` to point to whatever documents you want to li
 
 The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the errors in the Test interface.
 
-![On the CircleCI build results page there is a tab called Tests, which shows Spectral results so long as the JUnit format has been enabled](../img/ci-circleci.png)
+![On the CircleCI build results page there is a tab called Tests, which shows Spectral results if the JUnit format has been enabled](../img/ci-circleci.png)
 
 Learn more about [CircleCI Configuration](https://circleci.com/docs/2.0/config-intro/), or take a look at this [demo repository](https://github.com/philsturgeon/spectral-demo-circleci).
 
@@ -74,7 +74,3 @@ lint:spectral:
 Make sure to change `openapi.yaml` to point to whatever documents you want to lint.
 
 The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the Spectral output on the merge request page.
-
-## Jenkins
-
-Instructions coming soon.

docs/migration-guides/5.0.md

@@ -7,7 +7,7 @@ this migration guide covers the most notable changes.
 
 1. `oas2` and `oas3` rulesets have been merged to `oas`
 
-From now on, you don't need to worry about `oas2` or `oas3`, you simply extend the `oas` ruleset and Spectral figures out which rules to apply based on given formats.
+From now on, you don't need to worry about `oas2` or `oas3`. Simply extend the `oas` ruleset and Spectral figures out which rules to apply based on given formats.
 
 **Spectral v4**: