Merge branch 'docs-20200114-add-vale-config' into 'master'

Add Vale as an English language linter

See merge request gitlab-org/gitlab!23032

.vale.ini

+# Vale configuration file, taken from https://errata-ai.github.io/vale/config/
+
+# The relative path to the folder containing linting rules (styles)
+# -----------------------------------------------------------------
+StylesPath = doc/.linting/vale/styles
+
+# Minimum alert level
+# -------------------
+# The minimum alert level to display (suggestion, warning, or error).
+# If integrated into CI, builds fail by default on error-level alerts,
+# unless you execute Vale with the --no-exit flag
+MinAlertLevel = suggestion
+
+# Should Vale parse any file formats other than .md files as Markdown?
+# --------------------------------------------------------------------
+[formats]
+mdx = md
+
+# What file types should Vale test?
+# ----------------------------------
+[*.md]
+
+# Styles to load
+# --------------
+# What styles, located in the StylesPath folder, should Vale load?
+# Vale also currently includes write-good, proselint, joblint, and vale
+BasedOnStyles = gitlab
+
+# Enabling or disabling specific rules in a style
+# -----------------------------------------------
+# To disable a rule in an enabled style, use the following format:
+# {style}.{filename} = NO
+# To enable a single rule in a disabled style, use the following format:
+# vale.Editorializing = YES
+
+# Altering the severity of a rule in a style
+# ------------------------------------------
+# To change the reporting level (suggestion, warning, error) of a rule,
+# use the following format: {style}.{filename} = {level}
+# vale.Hedging = error
+
+# Syntax-specific settings
+# ------------------------
+# You can configure specific tests to be enabled, disabled, or report at a 
+# different level for specific file types. File-type-specific settings added
+# here will overwrite any conflicting global settings.
+[*.{md,txt}]
+# vale.Editorializing = NO
+

doc/.linting/vale/styles/gitlab/OxfordComma.yml

+extends: existence
+message: Use a comma before the last "and" in a list of three or more items.
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation
+level: warning
+tokens:
+  - '(?:[^,]+,){1,}\s\w+\sand'

doc/development/documentation/index.md

@@ -420,6 +420,7 @@ The following are some suggested linters you can install locally and sample conf
 
 - [`proselint`](#proselint)
 - [markdownlint](#markdownlint), which is the same as the test run in [`docs-lint`](#testing)
+- [Vale](#vale), for English language grammar and syntax suggestions
 
 NOTE: **Note:**
 This list does not limit what other linters you can add to your local documentation writing toolchain.
@@ -519,6 +520,23 @@ also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) t
 tracked the changes required to implement these rules, and details which rules were
 on or off when markdownlint was enabled on the docs.
 
+#### `Vale`
+
+[Vale](https://errata-ai.github.io/vale/) is a grammar, style, and word usage linter
+for the English language. Vale's configuration is stored in the
+[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file
+located in the root directory of the [GitLab repository](https://gitlab.com/gitlab-org/gitlab).
+
+Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/),
+stored in the `doc/.linting/vale/styles/gitlab` directory, that extend any of
+several types of checks.
+
+To view linting suggestions locally, you must install Vale on your own machine, and
+[configure the text editor of your choice](https://errata-ai.github.io/vale/#local-use-by-a-single-writer)
+to display the results.
+
+Vale's test results are not currently displayed in CI, but may be displayed in the future.
+
 ## Danger Bot
 
 GitLab uses [Danger](https://github.com/danger/danger) for some elements in