Add Vale for prose linting (#1099)

* feat: Add Vale configuration and rules

* docs: Fix top-level files to match Vale rules

* docs: Vale updates for the commands docs

* docs: apply Vale updates to the decorator docs

* docs: Update guides to match Vale rules

* docs: update rules and other content to meet Vale standards

* docs: add Vale link and information to CONTRIBUTING

* feat: Add GitHub action for Vale

* docs: minor editing to readme.md

* docs: minor editing to the changelog.md file

* docs: minor edits to the join.md file in commands folder

* docs: minor edits to lint.md file in the commands directory

* docs: minor edit to the login.md file in the commands directory

* docs: minor edits to the preview.md file in the commands directory

* docs: minor edits to push.md file in the comands directory

* docs: minor edits to the info-description-override.md file in the decorators directory

* docs: minor edits to the configure-rules.md file in the guides directory

* docs: minor edits to custom-plugin.md file in the resources directory

* docs: minor editing to the no-http-verbs-in-paths.md file in the rules directory

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

.github/CONTRIBUTING.md

@@ -11,7 +11,7 @@ Hi! We're really excited that you are interested in contributing to Redocly CLI.
 
 ## Issue Reporting Guidelines
 
-- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that by going to the [Issues page](https://github.com/Redocly/redocly-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one!
+- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that on the [Issues page](https://github.com/Redocly/redocly-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one!
 
 - The best way to get your bug fixed is to provide a (reduced) test case. This means listing and explaining the steps we should take to try and hit the same problem you're having. It helps us understand in which conditions the issue appears, and gives us a better idea of what may be causing it.
 
@@ -29,7 +29,7 @@ Before submitting a pull request, please make sure the following is done:
 
 ## Development Setup
 
-You will need [Node.js](http://nodejs.org) at `v12.0.0+`.
+[Node.js](http://nodejs.org) at `v12.0.0+` is required.
 
 After forking the repo, run:
 
@@ -74,6 +74,18 @@ There are some other scripts available in the `scripts` section of the `package.
 
 ## Contribute documentation
 
+### Prose linting
+
+We are proud of our docs. When you open a pull request, we lint the prose using [Vale](https://vale.sh/). You can also install this tool locally and run it from the root of the project with:
+
+```
+vale docs/
+```
+
+The configuration is in `.vale.ini` in the root of the project.
+
+### Markdown link checking
+
 We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder. This tool runs automatically on every pull request, but you can also run it locally if you want to. Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
 
 ```

.github/styles/Rules/BritishEnglish.yml

@@ -0,0 +1,110 @@
+extends: substitution
+message: 'Use the US spelling "%s" instead of British "%s".'
+link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
+level: error
+ignorecase: true
+swap:
+  aeon: eon
+  aeroplane: airplane
+  ageing: aging
+  aluminium: aluminum
+  anaemia: anemia
+  anaesthesia: anesthesia
+  analyse: analyze
+  annexe: annex
+  apologise: apologize
+  behaviour: behavior
+  busses: buses
+  calibre: caliber
+  cancelled: canceled
+  cancellation: cancelation
+  catalogue: catalog
+  categorise: categorize
+  categorised: categorized
+  categorises: categorizes
+  categorising: categorizing
+  centre: center
+  cheque: check
+  civilisation: civilization
+  civilise: civilize
+  colour: color
+  cosy: cozy
+  cypher: cipher
+  dependant: dependent
+  defence: defense
+  distil: distill
+  draught: draft
+  encyclopaedia: encyclopedia
+  enquiry: inquiry
+  enrol: enroll
+  enrolment: enrollment
+  enthral: enthrall
+  expiry: expiration
+  favourite: favorite
+  fibre: fiber
+  fillet: filet
+  flavour: flavor
+  furore: furor
+  fulfil: fulfill
+  gaol: jail
+  grey: gray
+  humour: humor
+  honour: honor
+  initialled: initialed
+  initialling: initialing
+  instil: instill
+  jewellery: jewelry
+  labelling: labeling
+  labelled: labeled
+  labour: labor
+  libellous: libelous
+  licence: license
+  likeable: likable
+  liveable: livable
+  lustre: luster
+  manoeuvre: maneuver
+  marvellous: marvelous
+  matt: matte
+  meagre: meager
+  metre: meter
+  modelling: modeling
+  moustache: mustache
+  neighbour: neighbor
+  normalise: normalize
+  offence: offense
+  organise: organize
+  organisation: organization
+  orientated: oriented
+  paralyse: paralyze
+  plough: plow
+  pretence: pretense
+  programme: program
+  pyjamas: pajamas
+  rateable: ratable
+  realise: realize
+  recognise: recognize
+  reconnoitre: reconnoiter
+  rumour: rumor
+  sabre: saber
+  saleable: salable
+  saltpetre: saltpeter
+  sceptic: skeptic
+  sepulchre: sepulcher
+  signalling: signaling
+  sizeable: sizable
+  skilful: skillful
+  sombre: somber
+  smoulder: smolder
+  speciality: specialty
+  spectre: specter
+  splendour: splendor
+  standardise: standardize
+  standardised: standardized
+  sulphur: sulfur
+  theatre: theater
+  travelled: traveled
+  traveller: traveler
+  travelling: traveling
+  unshakeable: unshakable
+  wilful: willful
+  yoghurt: yogurt

.github/styles/Rules/FutureTense.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: 'Avoid using future tense: "%s". Use present tense instead.'
+link: https://intranet.redoc.ly/contributing/documentation-style-guide/#tone-and-audience
+ignorecase: true
+level: error
+raw:
+  - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "will( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "won't( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)"

.github/styles/Rules/HeaderGerunds.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: 'Do not start headings with with a gerund (ing word). Use an imperative verb instead.'
+link: https://intranet.redoc.ly/contributing/documentation-style-guide/#content-organization
+level: error
+scope: heading
+tokens:
+  - '^\w*ing.*'

.github/styles/Rules/InclusionGenderCulture.yml

@@ -0,0 +1,16 @@
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+link: https://intranet.redoc.ly/contributing/documentation-style-guide/#grammar-and-syntax
+level: error
+ignorecase: true
+swap:
+  he: they
+  his: their
+  she: they
+  hers: their
+  blacklist(?:ed|ing|s)?: blocklist
+  whitelist(?:ed|ing|s)?: allowlist
+  master: primary, main
+  slave: replica
+  he/she: they
+  s/he: they

.github/styles/Rules/OxfordComma.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Use the Oxford comma in '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
+scope: sentence
+level: error
+nonword: true
+tokens:
+  - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]'

.github/styles/Vocab/Rules/accept.txt

@@ -0,0 +1,150 @@
+[Aa]nsible
+[Aa]utostart
+[Bb]locklist
+[Bb]locklists
+[Bb]oolean
+[Bb]reakpoint
+[B]reakpoints
+[Cc]ancelation
+[Cc]lassloading
+[Cc]hargeback
+[Cc]hargebacks
+[Cc]he
+[Cc]rypto
+[Cc]ryptocurrency
+[Dd]evfile|[Dd]evfiles
+[Dd]ownstream
+[Dd]ownstreaming
+[Ff]actories|[Ff]actory
+[Gg]it
+[Gg]rafana
+[Hh]eatmap
+[Hh]elm
+[Hh]ostname
+[Ii]tem
+[Jj]etbrains
+[Kk]eycloak
+[Ll]iveness
+[Ll]ombok
+[Ll]oopback
+[Mm]aven
+[Mm]inikube
+[Mm]inishift
+[Mm]ixin|[Mm]ixins
+[Mm]odularization
+[Mm]ulticluster
+[Mm]ultihost
+[Mm]ultinode
+[Mm]ultitenant
+[Mm]ultiuser
+[Mm]ultizone
+[Nn]amespace|[Nn]amespaces
+[Nn]etcoredebug[Oo]utput
+[Nn]ginx
+[Oo]nboarding
+[Pp]podman
+[Pp]reconfigured
+[Rr]eadonly
+[Rr]epresentment
+[Rr]ollout|[Rr]ollouts
+[Rr]untime|[Rr]untimes
+[Ss]erializer
+[Ss]erverless
+[Ss]ubnetwork
+[Ss]ubpath|[Ss]ubpaths
+[Tt]heia
+[Tt]olerations
+[Tt]ruststore
+[Uu]ninstallation
+[Uu]nstaged
+[Uu]ntrusted
+[Ww]orkspace|[Ww]orkspaces
+[Yy]eoman
+\.NET
+adoc
+Antora
+API
+Apigee
+AsciiDoc
+AWS|aws
+Azure
+Bierner
+Bitbucket
+btn
+Btrfs
+CentOS
+Ceph
+Che-Theia
+CLI
+ConfigMap|ConfigMaps
+Ctrl
+DaemonSet
+Dev Workspace
+Developer Perspective
+DNS
+Docker
+Dockerfile
+Dotnet
+Endevor
+endif
+GitHub|github
+GitLab
+Gluster
+Gradle
+Grafana
+GUI
+HTTPS|https
+I/O
+IDE|ide|IDEs
+Intelephense
+IntelliJ IDEA
+Java
+Java Lombok
+JSON|json
+JVM|jvm
+kbd
+Kubespray
+Laravel
+Let\'s Encrypt
+Mattermost
+mebibytes
+Microsoft Azure
+millicores
+Mulesoft
+MySQL
+Netlify
+Node.js
+npm
+NuGet
+OAuth
+ocp
+OmniSharp
+OpenShift
+OpenTracing
+Operator
+OperatorHub
+OpenAPI
+osd
+PHP
+PostgreSQL
+Quarkus
+Rebilly
+Redoc
+Redocly
+Redocly-cli
+SCM
+Sharding
+SonarLint
+Spring Boot
+SVG
+Uber
+URI|URIs
+URL|url|URLs
+Velero
+Vercel
+Visual Studio Code
+vsix
+Webview|Webviews
+Woopra
+YAML|yaml
+Zowe

.github/workflows/vale.yaml

@@ -0,0 +1,16 @@
+name: Docs lint
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  vale:
+    name: vale action
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: '["README.md", "docs"]'
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,48 @@
+# Vale configuration file.
+# See: https://docs.errata.ai/vale/config
+
+# The relative path to the folder containing linting rules (styles).
+StylesPath = .github/styles
+
+# Vocab define the exceptions to use in *all* `BasedOnStyles`.
+# spelling-exceptions.txt triggers `Vale.Terms`
+# reject.txt triggers `Vale.Avoid`
+# See: https://docs.errata.ai/vale/vocab
+Vocab = Rules
+
+# Minimum alert level
+# -------------------
+# The minimum alert level in the output (suggestion, warning, or error).
+# If integrated into CI, builds fail by default on error-level alerts, unless you run Vale with the --no-exit flag
+MinAlertLevel = suggestion
+
+# IgnoredScopes specifies inline-level HTML tags to ignore.
+# These tags may occur in an active scope (unlike SkippedScopes, skipped entirely) but their content still won't raise any alerts.
+# Default: ignore `code` and `tt`.
+IgnoredScopes = code, tt, img, url, a, body.id
+# SkippedScopes specifies block-level HTML tags to ignore. Ignore any content in these scopes.
+# Default: ignore `script`, `style`, `pre`, and `figure`.
+# For AsciiDoc: by default, listingblock, and literalblock.
+SkippedScopes = script, style, pre, figure, code, tt, listingblock, literalblock
+
+# Rules for matching file types. See: https://docs.errata.ai/vale/scoping
+
+[formats]
+properties = md
+mdx = md
+
+# Rules for .MD, .MDX
+[*.{md,mdx}]
+
+BasedOnStyles = Rules
+# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs.
+TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)
+Vale.Repetition = NO
+Vale.SentenceSpacing = NO
+Vale.Spelling = NO
+
+# /End of rules for .MD, .MDX
+
+
+# Process .ini files
+[*.ini]

README.md

@@ -55,7 +55,7 @@ Redocly CLI is a great way to render API reference documentation. It uses open s
 redocly build-docs openapi.yaml
 ```
 
-Your API reference docs will be in `redoc-static.html` by default. You can customise this in many ways, [read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information.
+Your API reference docs are in `redoc-static.html` by default. You can customize this in many ways. [Read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information.
 
 > :bulb: Redocly also has [hosted API reference docs](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/), a (commercial) alternative to Redoc. Both Redoc and Redocly API reference docs can be worked on locally using the `preview-docs` command.
 
@@ -71,7 +71,7 @@ redocly lint openapi.yaml
 
 **Format the output** in whatever way you need, the `stylish` output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, we've got those too.
 
-**Multiple files supported** so you don't need to bundle your API description in order to lint it, just give the entrypoint and Redocly CLI will do the rest.
+**Multiple files supported** so you don't need to bundle your API description to lint it, just give the entry point and Redocly CLI does the rest.
 
 [Learn more about API standards and configuring Redocly rules](https://redocly.com/docs/cli/api-standards).
 

docs/changelog.md

@@ -367,10 +367,10 @@ Technical release for changing the package name from `@redocly/openapi-cli` to `
 
 The product name has changed from OpenAPI CLI to **Redocly CLI**.
 
-You will notice this change reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section),
+This change is reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section),
-and later in the official project GitHub repository.
+and in the official project GitHub repository.
 
-The change also affects the CLI commands. The legacy name `openapi` will remain supported for a while, but we strongly recommend you use the new name `redocly`.
+The change also affects the CLI commands. The legacy name `openapi` is supported for now, but we strongly recommend you use the new name `redocly`.
 (To illustrate, if you previously used `openapi lint`, now you should use `redocly lint`).
 
 If you encounter any issues and suspect they may be related to this change, let us know by [reporting an issue](https://github.com/Redocly/redocly-cli/issues).
@@ -704,7 +704,7 @@ rules:
 
 ### Features
 
-- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API definitions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content will replace any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs.
+- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API definitions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content replaces any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs.
 
 The following examples show how to add the decorators to the `.redocly.yaml` file:
 
@@ -839,7 +839,7 @@ lint:
 
 - Resolved an issue with transitive $ref resolution in the JSON schema validator.
 
-- If the JSON schema validator crashes, OpenAPI CLI will now report the problem in the output instead of crashing itself.
+- If the JSON schema validator crashes, OpenAPI CLI reports the problem in the output instead of crashing itself.
 
 ---
 
@@ -903,7 +903,7 @@ lint:
 
 - Improved the error messages for `kebab-case` and implemented detection of `snake_case` usage in paths.
 
-- The `join` command will no longer overwrite an existing `x-displayName` of a tag with the tag's `name` property.
+- The `join` command does not overwrite an existing `x-displayName` of a tag with the tag's `name` property.
 
 ---
 
@@ -967,7 +967,7 @@ lint:
 
 ### Fixes
 
-- Resolved a hot-reloading issue with the `preview-docs` command. It will now automatically reload the docs in the browser when you make live changes to an OpenAPI definition.
+- Resolved a hot-reloading issue with the `preview-docs` command. It now automatically reloads the docs in the browser when you make live changes to an OpenAPI definition.
 
 ---
 
@@ -1015,7 +1015,7 @@ lint:
 
 ### Features
 
-- You can now use the `--verbose` parameter with the `login` command to show a detailed error trace (if any). Detailed error output will no longer be displayed by default for this command.
+- You can now use the `--verbose` parameter with the `login` command to show a detailed error trace (if any). Detailed error output is not displayed by default for this command.
 
 ---
 
@@ -1079,7 +1079,7 @@ lint:
 
 - Resolved an issue with `assert-node-version` using the wrong path.
 
-- OpenAPI CLI will now bundle the API definition before gathering stats.
+- OpenAPI CLI bundles the API definition before gathering stats.
 
 ---
 
@@ -1125,7 +1125,7 @@ lint:
 
 ### Features
 
-- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API definition files, and lets you choose the format in which the statistics will be presented.
+- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API definition files, and lets you choose the format in which the statistics are presented.
 
 ### Fixes
 

docs/commands/index.md

@@ -50,7 +50,7 @@ Redocly CLI comes with one primary configuration file (`redocly.yaml`), also kno
 This file defines all of the config options available to you, including the location of your files (for unbundling and bundling), and linting rules (for validation against the OpenAPI Specification).
 
 The Redocly configuration file must sit in your root directory.
-If Redocly CLI finds `redocly.yaml` in the root directory, it will use the options set in that file when executing commands.
+If Redocly CLI finds `redocly.yaml` in the root directory, it uses the options set in that file when executing commands.
 
 You can also specify a config file to most commands using `--config myconfig.yaml` as part of the command. For example:
 

docs/commands/join.md

@@ -20,9 +20,9 @@ With Redocly CLI, you can solve this problem by using the `join` command that ca
 
 To easily distinguish the origin of OpenAPI objects and properties, you can optionally instruct the `join` command to append custom prefixes to them.
 
-The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` file. Setting a custom name for this file can be achieved by providing it through the `--output` argument. Any existing file will be overwritten.
+The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` file. Setting a custom name for this file can be achieved by providing it through the `--output` argument. Any existing file is overwritten.
 
-Apart from providing individual API definition files as the input, you can also specify the path to a folder that contains multiple API definition files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command will collect all matching files and combine them into one file.
+Apart from providing individual API definition files as the input, you can also specify the path to a folder that contains multiple API definition files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command collects all matching files and combines them into one file.
 
 ### Usage
 
@@ -140,7 +140,7 @@ These options are mutually exclusive: `without-x-tag-groups`, `prefix-tags-with-
 
 ### prefix-tags-with-info-prop
 
-If any of the input files contain the `tags` object, tags in the output file will be prefixed by the selected property from the `info` object of the corresponding input file.
+If any of the input files contain the `tags` object, tags in the output file are prefixed by the selected property from the `info` object of the corresponding input file.
 
 The output file preserves the original tag names as the value of the `x-displayName` property for each tag.
 
@@ -162,7 +162,7 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
 
 ### prefix-tags-with-filename
 
-If any of the input files contain the `tags` object, tags in the output file will be prefixed by the filename of the corresponding input file.
+If any of the input files contain the `tags` object, tags in the output file are prefixed by the filename of the corresponding input file.
 
 The output file preserves the original tag names as the value of the `x-displayName` property for each tag.
 
@@ -184,7 +184,7 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
 
 ### without-x-tag-groups
 
-If you have the same tags in multiple API definitions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property will not be created in the joined file.
+If you have the same tags in multiple API definitions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.
 
 #### Usage
 
@@ -202,7 +202,7 @@ openapi.yaml: join processed in 69ms
 
 ### prefix-components-with-info-prop
 
-If any of the input files have conflicting component names, this option can be used to resolve that issue and generate the output file. All component names in the output file will be prefixed by the selected property from the `info` object of the corresponding input file(s).
+If any of the input files have conflicting component names, this option can be used to resolve that issue and generate the output file. All component names in the output file are prefixed by the selected property from the `info` object of the corresponding input file(s).
 
 #### Usage
 

docs/commands/lint.md

@@ -48,7 +48,7 @@ The `lint` command behaves differently depending on how you pass apis to it and
 redocly lint openapi/openapi.yaml
 ```
 
-In this case, `lint` will validate the definition(s) passed to the command. The configuration file is ignored.
+In this case, `lint` validates the definition(s) passed to the command. The configuration file is ignored.
 
 The `apis` argument can also use any glob format supported by your file system. For example, `redocly lint ./root-documents/*.yaml`.
 
@@ -66,7 +66,7 @@ apis:
     root: ./openapi/definition.json
 ```
 
-In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` will validate the `definition.json` file. The presence of the Redocly configuration file is mandatory.
+In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `definition.json` file. The presence of the Redocly configuration file is mandatory.
 
 #### Empty apis
 
@@ -90,7 +90,7 @@ In this case, if no API definitions are specified, `lint` validates all apis lis
 
 :::warning Important
 
-If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command will display an error.
+If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command displays an error.
 
 :::
 
@@ -104,7 +104,7 @@ redocly lint --config=./another/directory/config.yaml
 
 ### Extend configuration
 
-The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, `all`. Each of the values is a base set of rules that the lint command will use. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs.
+The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, or `all`. Each of the values is a base set of rules that the lint command uses. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs.
 
 :::warning Important
 
@@ -193,7 +193,7 @@ redocly lint --max-problems 200
 
 ### Generate ignore file
 
-With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You will still receive visual feedback to let you know how many problems were ignored.
+With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored.
 
 This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control.
 
@@ -207,7 +207,7 @@ Generated ignore file with 3 problems.
 ```
 
 :::warning
-This command will overwrite an existing ignore file.
+This command overwrites an existing ignore file.
 :::
 
 To generate an ignore file for multiple definitions, pass them as arguments:

docs/commands/login.md

@@ -10,9 +10,9 @@ Before proceeding with the command, [generate a personal API key](../../settings
 
 Use the `login` command to authenticate to the API registry.
 
-When you log in, the `preview-docs` command will start a preview server using Redocly API reference docs with all of the premium features.
+When you log in, the `preview-docs` command starts a preview server using Redocly API reference docs with all of the premium features.
 
-Also, you will be able to access your members-only (private) API definitions in the Redocly registry, and use the [`push`](./push.md) command.
+Also, you can access your members-only (private) API definitions in the Redocly registry, and use the [`push`](./push.md) command.
 
 If you're having issues with the `login` command, use the `--verbose` option to display a detailed error trace (if any).
 

docs/commands/preview-docs.md

@@ -4,7 +4,7 @@
 
 With this command, you can generate documentation previews for API definitions on your local machine.
 
-If you have a license key or API key, you will get a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). If you don't, you will get a preview of [Redoc community edition](https://redocly.com/redoc/).
+If you have a license key or API key configured, the output is a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). Otherwise, it is a preview of [Redoc community edition](https://redocly.com/redoc/).
 
 :::success Tip
 To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the [`login`](./login.md) command.
@@ -46,7 +46,7 @@ The command behaves differently depending on how you pass the api to it, and whe
 redocly preview-docs openapi/openapi.yaml
 ```
 
-In this case, `preview-docs` will preview the definition that was passed to the command. The configuration file is ignored.
+In this case, `preview-docs` previews the definition that was passed to the command. The configuration file is ignored.
 
 #### Pass api alias
 
@@ -86,11 +86,11 @@ redocly preview-docs -p 8888 openapi/openapi.yaml
 redocly preview-docs -port 8888 openapi/openapi.yaml
 ```
 
-Both commands will start the preview on port `8888`, so you can access the docs at `http://localhost:8888`
+Both commands start the preview on port `8888`, so you can access the docs at `http://localhost:8888`.
 
 ### Custom host for preview
 
-By default, without using the `host` option, the preview starts on host `127.0.0.1`, so you can access the docs at `http://127.0.0.1:8080` or `http://localhost:8080`
+By default, without using the `host` option, the preview starts on host `127.0.0.1`, so you can access the docs at `http://127.0.0.1:8080` or `http://localhost:8080`.
 
 To specify a custom host for the preview, pass the desired value using either short or long option format:
 
@@ -102,7 +102,7 @@ redocly preview-docs -h 0.0.0.0 openapi/openapi.yaml
 redocly preview-docs --host 0.0.0.0 openapi/openapi.yaml
 ```
 
-Both commands will start the preview on host `0.0.0.0`, so you can access the docs at `http://0.0.0.0:8080`
+Both commands start the preview on host `0.0.0.0`, so you can access the docs at `http://0.0.0.0:8080`
 
 ### Skip preprocessor or decorator
 

docs/commands/push.md

@@ -14,22 +14,22 @@ This allows you to:
 Apart from uploading your API definition file, the `push` command can automatically upload other files if they are detected or referenced in the API definition:
 
 - the [Redocly configuration file](/docs/cli/configuration/index.mdx) and any configuration files referenced in the `extends` list.
-- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows will use the `@redocly/cli` version specified in `package.json`.
+- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows uses the `@redocly/cli` version specified in `package.json`.
 - the HTML template and the full contents of the folder specified as the `theme > openapi > htmlTemplate` parameter in the Redocly configuration file.
 
 :::attention
 
-If a plugin is referenced in the Redocly configuration file, the `push` command will recursively scan the folder containing the plugin and upload all `.js`, `.json`, `.mjs` and `.ts` files.
+If a plugin is referenced in the Redocly configuration file, the `push` command recursively scans the folder containing the plugin and uploads all `.js`, `.json`, `.mjs` and `.ts` files.
 
-Make sure that each plugin has all the required files in its folder, otherwise they will not be uploaded.
+Make sure that each plugin has all the required files in its folder; otherwise, they are not uploaded.
 
 :::
 
-By default, the `push` command only updates an existing API definition version. If an API with the provided name and version doesn't exist in your organization, it will not be created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section.
+By default, the `push` command only updates an existing API definition version. If an API with the provided name and version doesn't exist in your organization, it isn't created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section.
 
 :::warning
 
-Only API definitions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources will fail with an error.
+Only API definitions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources fails with an error.
 
 :::
 
@@ -44,7 +44,7 @@ Before using the `push` command, ensure the following prerequisites are met:
 
 To authenticate to the API registry, you can use several approaches:
 
-- use the [`login` command](login.md). In this case, the command will look as follows:
+- use the [`login` command](login.md). In this case, the command is as follows:
 
   ```bash
   redocly login
@@ -80,8 +80,8 @@ redocly push [-u] [--batch-id id] [--batch-size number] <path/to/definition.yaml
 | ---------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | api              |  string  | The API definition that you want to push to the Redocly API registry. Provide it as a path to the root API definition file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information.                                                                                                                    |
 | destination      |  string  | Conditional. The location in the API registry where you want to push or upsert your API definition. Provide it in the following format: `@organization-id/api-name@api-version` or `api-name@api-version`if organization ID is already defined in the configuration file. See [the Destination section](#destination) for more information. |
-| --branch, -b     |  string  | The branch where your API definition will be pushed or upserted. Default value is `main`.                                                                                                                                                                                                                                                   |
+| --branch, -b     |  string  | The branch where your API definition is pushed or upserted. Default value is `main`.                                                                                                                                                                                                                                                   |
-| --batch-id       |  string  | Specifies the ID of the CI job that the current push will be associated with. See [the Batch ID section](#batch-id) for more information.                                                                                                                                                                                                   |
+| --batch-id       |  string  | Specifies the ID of the CI job that the current push is associated with. See [the Batch ID section](#batch-id) for more information.                                                                                                                                                                                                   |
 | --batch-size     |  number  | Specifies the total number of CI jobs planned to be pushed within one batch. See [the Batch Size section](#batch-size) for more information.                                                                                                                                                                                                |
 | --help           | boolean  | Help output for the command.                                                                                                                                                                                                                                                                                                                |
 | -- public        | boolean  | Make API definitions publicly accessible from the API Registry. Read more about [using the public option](#public).                                                                                                                                                                                                                         |
@@ -90,7 +90,6 @@ redocly push [-u] [--batch-id id] [--batch-size number] <path/to/definition.yaml
 | --upsert, -u     | boolean  | Upsert an API to the API registry. See [the Upsert an API with push section](#upsert-an-api-with-push) for more information.                                                                                                                                                                                                                |
 | --version        | boolean  | Show version number.                                                                                                                                                                                                                                                                                                                        |
 | --files          | [string] | List of other folders and files to upload. See [the Files section](#files) for more information.                                                                                                                                                                                                                                            |
-
 ## Examples
 
 The command behaves differently depending on the options you pass to it and whether the configuration file exists in your working directory.
@@ -143,7 +142,7 @@ When using the `push` command, you would provide the API name after the [Organiz
 
 :::attention
 
-The name of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character will result in an error, and your API will not be created.
+The name of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
 
 :::
 
@@ -160,7 +159,7 @@ When using the `push` command, you would provide the API version after the [API
 
 :::attention
 
-The version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character will result in an error, and your API will not be created.
+The version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
 
 :::
 
@@ -172,7 +171,7 @@ Provide the `api` as a path to the root API definition file, and specify the org
 redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1
 ```
 
-In this case, `push` will upload only the definition that was passed to the command. The configuration file is ignored.
+In this case, `push` uploads only the definition that was passed to the command. The configuration file is ignored.
 
 To push the definition to a particular branch, specify the branch name.
 
@@ -252,7 +251,7 @@ Must be used only in combination with the `--batch-size` option.
 
 ### Batch Size
 
-The `--batch-size` option can be used by Redocly Workflows to understand how many pushes in total will be performed within one batch to properly handle parallel pushes.
+The `--batch-size` option can be used by Redocly Workflows to understand how many pushes in total are performed within one batch to properly handle parallel pushes.
 
 Must be used only in combination with the `--batch-id` option. Must be an integer bigger than 1.
 

docs/commands/split.md

@@ -21,7 +21,7 @@ redocly split --version
 Option | Type | Description
 -- | -- | --
 api | string | **REQUIRED.** Path to the API definition file that you want to split into a multi-file structure.
---outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it will be created automatically.
+--outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it is created automatically.
 --help | boolean | Show help.
 --separator | string | File path separator used while splitting. The default value is `_`. This controls the file names generated in the `paths` folder (e.g. `/users/create` path becomes `user_create.yaml`).
 --version | boolean | Show version number.

docs/commands/stats.md

@@ -43,7 +43,7 @@ The `stats` command behaves differently depending on how you pass the api to it
 redocly stats openapi/openapi.yaml
 ```
 
-In this case, `stats` will show statistics for the definition that was passed to the command. The configuration file is ignored.
+In this case, `stats` shows statistics for the definition that was passed to the command. The configuration file is ignored.
 
 #### Pass api via configuration file
 

docs/decorators.md

@@ -13,16 +13,16 @@ They are commonly used to add, remove, or change content.
 
 ## List of decorators
 
-### Changing descriptions
+### Update descriptions
 - [info-description-override](./decorators/info-description-override.md)
 - [info-override](./decorators/info-override.md)
 - [operation-description-override](./decorators/operation-description-override.md)
 - [tag-description-override](./decorators/tag-description-override.md)
 
-### Changing examples
+### Change examples
 - [media-type-examples-override](./decorators/media-type-examples-override.md)
 
-### Removing content
+### Remove content
 
 - [filter-in](./decorators/filter-in.md)
 - [filter-out](./decorators/filter-out.md)

docs/decorators/filter-in.md

@@ -10,7 +10,7 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
 
 |Option|Type|Description|
 |---|---|---|
-|property|string|**REQUIRED.** The property name used for evaluation. It will attempt to match the values.|
+|property|string|**REQUIRED.** The property name used for evaluation. It attempts to match the values.|
 |value|[string]|**REQUIRED.** List of values used for the matching.|
 |matchStrategy|string|Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`.|
 

docs/decorators/filter-out.md

@@ -11,7 +11,7 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
 
 |Option|Type|Description|
 |---|---|---|
-|property|string|**REQUIRED.** The property name used for evaluation. It will attempt to match the values.|
+|property|string|**REQUIRED.** The property name used for evaluation. It attempts to match the values.|
 |value|[string]|**REQUIRED.** List of values used for the matching.|
 |matchStrategy|string|Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`.|
 

docs/decorators/info-description-override.md

@@ -5,8 +5,8 @@ Replaces the info description with the designated Markdown in the corresponding
 ## API design principles
 
 Sometimes developers generate OpenAPI and the descriptions need to be improved after the fact.
-This generally happens when you have no permission to edit the source.
+This generally happens when you don't have permission to edit the source.
-This decorator provides a way to "overlay" a new description over the source so that as the source changes you won't lose your modifications.
+This decorator provides a way to "overlay" a new description over the source, so that as the source changes, the modifications can be reapplied.
 
 
 ## Configuration

docs/decorators/info-override.md

@@ -6,7 +6,7 @@ Extends the info object with the designated value.
 
 Sometimes developers generate OpenAPI and the info object need to be improved after the fact.
 This generally happens when you have no permission to edit the source.
-This decorator provides a way to "overlay" a new info section over the source so that as the source changes you won't lose your modifications.
+This decorator provides a way to "overlay" a new info section over the source so that as the source changes, the modifications can be reapplied.
 
 
 ## Configuration

docs/decorators/media-type-examples-override.md

@@ -6,7 +6,7 @@ Replaces the examples in the corresponding file.
 
 Sometimes developers generate OpenAPI and the examples need to be added or improved after the fact.
 This generally happens when you have no permission to edit the source.
-This decorator provides a way to "overlay" a new examples over the source so that as the source changes you won't lose your modifications.
+This decorator provides a way to "overlay" a new examples over the source so that as the source changes, the modifications can be reapplied.
 
 ## Configuration
 

docs/decorators/operation-description-override.md

@@ -6,7 +6,7 @@ Replaces the operation description with the designated Markdown in the correspon
 
 Sometimes developers generate OpenAPI and the descriptions need to be improved after the fact.
 This generally happens when you have no permission to edit the source.
-This decorator provides a way to "overlay" a new description over the source so that as the source changes you won't lose your modifications.
+This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modification can be reapplied
 
 
 ## Configuration

docs/decorators/tag-description-override.md

@@ -6,7 +6,7 @@ Replaces the tag description with the designated Markdown in the corresponding f
 
 Sometimes developers generate OpenAPI and the descriptions need to be improved after the fact.
 This generally happens when you have no permission to edit the source.
-This decorator provides a way to "overlay" a new description over the source so that as the source changes you won't lose your modifications.
+This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modifications can be reapplied. 
 
 
 ## Configuration

docs/file-management.md

@@ -16,7 +16,7 @@ If you have one large single file, split it up like this:
 redocly split openapi.yaml --outDir myApi
 ```
 
-The original file is unchanged, but look in the directory named by the `--outDir` parameter and you will find:
+The original file is unchanged, but look in the directory named by the `--outDir` parameter. It now contains:
 * An `openapi.yaml` file, which is the entry point of the API and includes the `info` section and other metadata. This file also contains the bare bones of the API description, with all the details moved to dedicated files.
 * A `paths/` directory, with a file for each of the URLs in the API. All verbs for that endpoint are in this file.
 * A `components/` directory containing subdirectories for each of the top-level keys, such as `schema`, and files for the individual data structures described in each section.

docs/guides/configure-rules.md

@@ -1,8 +1,11 @@
 # Configure API linting
 
-Every API has a different purpose and therefore different standards will apply. If you work in high security financial data, you will want a higher level of compliance with API standards than if you are creating a quick backend for a web application. Configuring an appropriate combination of rules is important; if the standards are too harsh, you risk ignoring errors and missing something important, but if they are too lax then your OpenAPI description may be inconsistent or incomplete for your needs.
+Every API has a different purpose and therefore different standards apply.
+If you work in high security financial data, you may want a higher level of compliance with API standards than if you are creating a quick backend for a web application. Configuring an appropriate combination of rules is important;
+if the standards are too harsh, you risk ignoring errors and missing something important,
+but if they are too lax then your OpenAPI description may be inconsistent or incomplete for your needs.
 
-In this guide, you will learn how to chose and adapt the rules built into Redocly for your own needs.
+In this guide, learn how to choose and adapt the rules built into Redocly for your own needs.
 
 ## Pick an existing ruleset
 
@@ -17,7 +20,7 @@ You can specify the ruleset with the `lint` command in Redocly CLI like this:
 redocly lint --extends recommended openapi.yaml
 ```
 
-However for anything more complicated, or to use the functionality with the API registry, the best way to configure the linting rules is in the configuration file.
+However, for anything more complicated, or to use the functionality with the API registry, the best way to configure the linting rules is in the configuration file.
 
 ## Create reusable configuration
 
@@ -38,7 +41,7 @@ You can also define rulesets and other linting details differently for each API
 
 ## Adjust the rules in use
 
-The recommended ruleset aims to be best practice for all use cases, but of course every situation is different and some of the defaults won't fit your needs. You can tweak existing rulesets by turning rules on or off, or setting them to be warnings or errors.
+The recommended ruleset aims to be best practice for all use cases, but of course every situation is different and some of the defaults may not fit your needs. You can tweak existing rulesets by turning rules on or off, or setting them to be warnings or errors.
 
 As an example, here's a configuration file for a public API, where the rule `security-defined` shouldn't cause an error:
 

docs/guides/hide-apis.md

@@ -13,8 +13,8 @@ Follow along using our sample API provided with this tutorial to hide APIs, and
 
 ## Overview
 
-In this tutorial, we'll maintain a single source of truth (SSOT) OpenAPI definition.
+In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI definition.
-Then, we'll generate an internal and an external version of the API.
+Once the definition is complete, generate an internal and an external version of the API.
 
 ```mermaid
 graph TD
@@ -22,7 +22,7 @@ graph TD
     A[SSOT] -->|bundle| C(External)
 ```
 
-The following image highlights what we'll remove in this tutorial.
+The following image highlights what is to be removed in this tutorial.
 ![what needs to be hidden](./images/hide-internal-apis-problem.png)
 
 ## Prerequisites
@@ -37,9 +37,9 @@ This tutorial is most effective when you follow along and complete the steps.
 
 ## Step 1: Add `x-internal` to the API definition
 
-In this step, you will mark operations and properties of the API definition as internal.
+In this step, mark which operations and properties of the API definition are for internal use.
 
-Open the `sample.yaml` file in your IDE. We'll change it in a few places.
+Open the `sample.yaml` file in your IDE. Changes are needed in a few places.
 
 1. Go to line 22 and add a new line between `post` and `operationId`.
   The indentation is important.
@@ -61,7 +61,7 @@ Open the `sample.yaml` file in your IDE. We'll change it in a few places.
 
 ## Step 2: Add a Redocly configuration file
 
-In this step, you will create a Redocly configuration file with two APIs pointing to the same root file.
+In this step, create a Redocly configuration file with two APIs pointing to the same root file.
 
 Make a new file in the same `hide-apis-demo` directory named `redocly.yaml` (the casing is important).
 
@@ -105,7 +105,7 @@ Save the `redocly.yaml` file.
 
 ## Step 3: Output internal and external APIs
 
-In this step, you'll produce the two API snapshots from the single source of truth.
+In this step, produce two API snapshots from the single source of truth.
 This can be done in two ways:
 
 - Option A: Let Redocly's API registry handle the work (which uses the `bundle` command under the hood).
@@ -114,7 +114,7 @@ This can be done in two ways:
 ### Option A: Redocly's API registry bundles automatically
 
 1. Add the APIs to the API registry.
-  This process will vary depending on the source type you use.
+  This process varies depending on the source type you use.
   If using the CICD `push` command, it can push all APIs or the API you specify by the API `name@version`.
   If using a git-based integration, select the appropriate API in the path to your root file.
 

docs/guides/hide-specification-extensions.md

@@ -1,13 +1,13 @@
 # Hide OpenAPI specification extensions
 
 When you want to hide internal operations and properties, you can follow our [hide internal APIs](./hide-apis.md) guide.
-However, this approach won't work if you use [specification extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/)
+However, this approach doesn't work if you use [specification extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/)
 in your API and want to hide their details as well. For this purpose, you need a custom decorator.
 
 ## Overview
 
-In this tutorial, we'll maintain a single source of truth (SSOT) OpenAPI definition.
+In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI definition.
-Then, we'll generate an internal and an external version of the API.
+Then generate an internal and an external version of the API.
 
 ```mermaid
 graph TD
@@ -92,7 +92,7 @@ You can name the decorators directory anything you want. Make sure you use the c
 
 ## Step 3: Configure the plugin for use
 
-To use the decorator, you will need to register your plugin in your Redocly configuration file `redocly.yaml`. Register your `plugins` and `decorators`.
+To use the decorator, register your plugin in your Redocly configuration file `redocly.yaml`. Register your `plugins` and `decorators`.
 
 ```yaml
 apis:
@@ -124,7 +124,7 @@ Make sure your `hide-openapi-extensions` looks as follows:
 
 ## Step 4: Output internal and external APIs
 
-In this step, you'll produce the two API snapshots from the single source of truth. To do this, you can use the [`bundle` command](../commands/bundle.md) on your machine.
+In this step, two API snapshots are produced from the single source of truth. To do this, you can use the [`bundle` command](../commands/bundle.md) on your machine.
 
 1. Bundle the `external@latest` API.
 

docs/guides/replace-servers-url.md

@@ -75,7 +75,7 @@ You can name the plugins directory and file anything you want. Make sure you use
 
 ## Step 2: Add a decorator and associate it with an environment variable
 
-In this step, you will add a decorator and define the environment variable associated with it.
+In this step, add a decorator and define the environment variable associated with it.
 
 1. Create a directory `decorators` inside of the `plugins` directory.
 1. Create a `replace-servers-url.js` file with this information and save it inside of the `decorators` directory.
@@ -108,7 +108,7 @@ You can name the decorators directory anything you want. Make sure you use the c
 
 ## Step 3: Configure the plugin for use
 
-To use the decorator, you will need to register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`.
+To use the decorator, register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`.
 
 ```yaml
 apis:

docs/guides/response-contains-property.md

@@ -19,7 +19,7 @@ Let's get started!
 
 ## Before you begin
 
-- [Use the openapi-starter repository](../openapi-starter.md) to set up a basic project that we will use for this guide.
+- [Use the openapi-starter repository](../openapi-starter.md) to set up a basic project for use with this guide.
 - [Download the modified project files](https://gist.github.com/bandantonio/c6047e3ee70c90da013a2f8e6757edb0) and use them to
 replace the corresponding files in the `openapi` folder:
 

docs/guides/update-cli.md

@@ -5,7 +5,7 @@ redirectFrom:
 
 # Update Redocly CLI
 
-If you've already installed Redocly CLI, you'll want to keep it as up to date as possible. Staying on top of versions ensures that you get the latest functionality and bug fixes.
+If you've already installed Redocly CLI, it is good practice to keep it as up to date as possible. Staying on top of versions ensures that you get the latest functionality and bug fixes.
 
 If you [installed Redocly CLI globally](../installation.md), run this command:
 

docs/index.md

@@ -20,7 +20,7 @@ Redocly CLI is an open source command-line tool for working with OpenAPI descrip
 
 Redoc is our open source API documentation tool. Use `redocly` (this project) to work with your Redoc documentation projects.
 
-The Redocly CLI also supports many of the other operations you'll need to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool.
+The Redocly CLI also supports many of the other operations needed to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool.
 
 Redocly offers a full suite of API lifecycle tools as commercial offerings; you can manage those from this tool too.
 

docs/installation.md

@@ -20,11 +20,11 @@ npm i -g @redocly/cli@latest
 yarn global add @redocly/cli
 ```
 
-Running `redocly --version` will confirm that the installation was successful, and the currently-installed version of the tool.
+Running `redocly --version` confirms that the installation was successful, and the currently-installed version of the tool.
 
 ## Use `npx` at runtime
 
-[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It will install and run a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times.
+[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It installs and runs a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times.
 
 ```shell Command
 npx @redocly/cli <command> [options]

docs/openapi-starter.md

@@ -24,7 +24,7 @@ Clone the project to your local machine so you can use it with [Redocly CLI](qui
 
 ## Step 3: Work with OpenAPI
 
-By default, you will have a root directory (`openapi`) that contains a sample API definition file (`openapi.yaml`). The sample file is already split into its constituent parts, which are contained in the `code_samples`, `components` and `paths` folders.
+By default, there is a root directory (`openapi`) that contains a sample API definition file (`openapi.yaml`). The sample file is already split into its constituent parts, which are contained in the `code_samples`, `components` and `paths` folders.
 
 ### Just starting out with API docs?
 
@@ -34,4 +34,4 @@ Use our `openapi.yaml` file to explore Redocly CLI. We suggest you [run some bas
 
 You can add your files straight into the `openapi` folder and use the existing sub-folders when splitting them up for easier maintenance (`split` command) and compiling them back into a single file (`bundle`) for publishing out. Be aware that the more definitions stored in the `openapi` folder, the more cluttered the sub-folders. But hey, if you like clutter then go for it!
 
-Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in Redocly CLI for a specified definition file, the sub-folders will automatically be created under the root and populated with the constituent parts of your main definition file.
+Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in Redocly CLI for a specified definition file, the sub-folders are automatically created under the root and populated with the constituent parts of your main definition file.

docs/resources/custom-plugins.md

@@ -13,7 +13,7 @@ Redocly recommends using the highly [configurable rules](../rules/configurable-r
 ## Concepts
 
 Extend the CLI through the use of custom plugins.
-There are three main differences between preprocessors, rules and decorators.
+There are three main differences between preprocessors, rules, and decorators.
 
 1. The order of execution:
 
@@ -29,7 +29,7 @@ There are three main differences between preprocessors, rules and decorators.
 1. Preprocessors and decorators do not support nested visitors.
 
 ### Plugins
-A plugin defines a configuration and set of rules, preprocessors and decorators.
+A plugin defines a configuration and set of rules, preprocessors, and decorators.
 
 Plugins need to be explicitly defined in the configuration file (except for the Redocly built in plugins).
 
@@ -90,12 +90,12 @@ See an example of a custom rule implementation in our ["Response contains proper
 
 Keys of the object can be any of the following:
 
-- node type - visitor will be called on specific node type. List of available node types for each specific OAS version:
+- node type - the visitor is called on specific node types. List of available node types for each specific OAS version:
   - OAS 3.1: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas3_1.ts#L209
   - OAS 3.0: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas3.ts#L530
   - OAS 2.0: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas2.ts#L367
-- `any` - visitor will be called on every node
+- `any` - visitor is called on every node.
-- `ref` - visitor will be called on $ref nodes
+- `ref` - visitor is called on $ref nodes.
 
 The value of each node can be either **visitor function** (runs while going down the tree) or **visitor object** (see below).
 
@@ -128,7 +128,9 @@ Also, visitor object (if it is not `any` or `ref`) can define [nested visitors](
 
 ## Visitors execution and $ref
 
-Top level **visitor functions** run only once for each node. If the same node is referenced via $ref multiple times top-level **visitor functions** will be executed only once for this node.
+Top level **visitor functions** run only once for each node.
+If the same node is referenced by the $ref multiple times,
+top-level **visitor functions** are executed only once for this node.
 
 This works fine for most context-free rules which check basic things. If you need contextual info you should use [nested visitors](#nested-visitors).
 
@@ -151,7 +153,7 @@ function ExampleRule() {
 }
 ```
 
-The `Schema` **visitor function** will be called by Redocly CLI if only Schema Object is encountered while traversing a tree while the Operation Object is **entered**.
+The `Schema` **visitor function** is called by Redocly CLI only if the Schema Object is encountered while traversing a tree while the Operation Object is **entered**.
 
 As the third argument, the **visitor function** accepts the `parents` object with corresponding parent nodes as defined in the **visitor object**.
 
@@ -184,7 +186,7 @@ put:
         type: number
 ```
 
-The visitor above will log the following:
+The visitor above logs the following:
 
 ```
 type string from get
@@ -226,7 +228,7 @@ and the following methods:
 
 ## context.report()
 
-The main method you'll use is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties:
+The main method used is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties:
 
 - `message` - {string} the problem message.
 - `location` - {Location} (optional) an object specifying the location of the problem. Can be constructed using location object methods.
@@ -392,7 +394,7 @@ The type tree is built from top level `Types` which can link to child types.
 
 This tree can be extended or modified.
 
-## Extending type definitions
+## Extend type definitions
 
 The type tree can be extended by exporting the `typeExtension` function from a custom plugin.
 Follow this pattern (similar to reducers if you're familiar with the map-reduce pattern):

docs/rules.md

@@ -39,4 +39,4 @@ Severity settings determine how the rule is treated during the validation proces
 ## Rule ideas
 
 Redocly CLI supports [custom rules](./rules/configurable-rules.md) and [custom plugins](./resources/custom-plugins.md).
-However, if you have an idea for a built-in rule you believe will benefit the greater API community, please [open an issue](https://github.com/Redocly/redocly-cli/issues/new) in the Redocly CLI repository.
+However, if you have an idea for a built-in rule you believe benefits the greater API community, please [open an issue](https://github.com/Redocly/redocly-cli/issues/new) in the Redocly CLI repository.

docs/rules/info-license-url.md

@@ -23,9 +23,7 @@ The principle of providing your users with accurate and relevant information doe
 
 Before they can work with your API, your users must understand the terms and conditions of your API usage.
 
-"Can I use your API? Will I get in trouble? Will I lose my job?"
+By being upfront with the API license, you can reduce friction and encourage API adoption.
-Sometimes questions like these go through consumers' minds.
-By being upfront with the API license, you can reduce friction towards usage.
 
 ## Configuration
 

docs/rules/info-license.md

@@ -23,9 +23,7 @@ The principle of providing your users with accurate and relevant information doe
 
 Before they can work with your API, your users must understand the terms and conditions of your API usage.
 
-"Can I use your API? Will I get in trouble? Will I lose my job?"
+By being upfront with the API license, you can reduce friction and encourage API adoption.
-Sometimes questions like these go through consumers' minds.
-By being upfront with the API license, you can reduce friction towards usage.
 
 ## Configuration
 

docs/rules/no-http-verbs-in-paths.md

@@ -34,9 +34,10 @@ The REST type prefers to name paths after resources like "customers", and "payme
 And the REST type relies on HTTP methods, like GET, to indicate the action on that resource.
 It would be considered a design fail to make the path "getcustomers" or "get-customers" or any variation on that.
 If you're aiming to design RESTful resources, then consider this rule your friend.
-There is the option to `splitIntoWords` to reduce false positives.
+
+To reduce false positives, use the `splitIntoWords` option.
 Imagine a world-famous rock band, the Redockers, and they have an API powering their music tour with one resource "posters".
-With the `splitIntoWords` enabled it will be identified as a resource and not trigger a false positive even though it contains the word `post`.
+With the `splitIntoWords` option enabled, "posters" is identified as a resource and does not trigger a false positive, even though it contains the word `post`.
 
 ## Configuration
 
@@ -113,7 +114,7 @@ paths:
     $ref: ./paths/customer.yaml
 ```
 
-This last example wouldn't trigger an error because the casing won't split "get" into its own word.
+This last example wouldn't trigger an error because the casing doesn't split "get" into its own word.
 
 ## Related rules
 

docs/rules/operation-description.md

@@ -13,13 +13,7 @@ Requires the `description` field for every operation in your API.
 
 Every operation should have a description to help your API consumers understand what it does and how to use it.
 Without a description, people who want to use your API have to guess what an operation does, or try to decipher it from other parts of your API definition, or from other documentation and external resources that may not be accurate. Your API definition should be the single source of truth about your API.
-
+Add the description field and delight both your (future) teammates and your API consumers.
-Okay, so we're documentation folks here.
-You're thinking, "of course they would say that."
-You're right!
-And we're right!
-Do this, and your (future) teammates will thank you.
-Do this, and your API consumers will thank you.
 
 ## Configuration
 

docs/rules/path-segment-plural.md

@@ -18,7 +18,7 @@ For example, "customers" instead of "customer" because:
 - `GET /customers` means getting a collection of customers
 - `GET /customers/abc` means getting customer ABC from the customers collection
 
-As your API grows, you'll likely hit some false positives and may also need to ignore a few outliers.
+As your API grows, you may hit some false positives and may also need to ignore a few outliers.
 That is, unless you're a purist.
 Nothing wrong with that.