Add linting section to documentation guidelinesdocs/linters-in-editors

2 files changed, 74 insertions, 2 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index d6ae4cb39f0..a413e4b4639 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -43,13 +43,13 @@ how to structure GitLab docs.
 
 Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
 
-All the docs follow the [documentation style guidelines](styleguide.md).
+All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines.
 
 ## Documentation directory structure
 
 The documentation is structured based on the GitLab UI structure itself,
 separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user),
-[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). 
+[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development).
 
 In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
 all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent.
@@ -223,6 +223,76 @@ redirect_from: 'https://docs.gitlab.com/my-old-location/README.html'
 Note: it is necessary to include the file name in the `redirect_from` URL,
 even if it's `index.html` or `README.html`.
 
+## Linting
+
+To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content added to documentation, consider adding documentation linters to your documentation writing toolchain. This will help you catch common issues before submitting documentation for review.
+
+The following are some suggested linters and sample configuration:
+
+- `proselint`
+- `markdownlint`
+
+NOTE: **Note:**
+This list does not limit what other linters you can add to your documentation writing toolchain.
+
+### `proselint`
+
+`proselint` checks for common problems with English prose. It provides a [plethora of checks](http://proselint.com/checks/) that are helpful for technical writing.
+
+`proselint` can be used [on the command line](http://proselint.com/utility/), or within text editors using plugins. For example, for:
+
+- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-proselint)
+- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=PatrykPeszko.vscode-proselint)
+- [Others](https://github.com/amperser/proselint#plugins-for-other-software)
+
+#### Sample `proselint` configuration
+
+All of the checks are good to use. However, excluding the `typography.symbols` checks might reduce noise. The following sample `proselint` configuration disables the `typography.symbols` checks:
+
+```json
+{
+  "checks": {
+    "typography.symbols": false
+  }
+}
+```
+
+### `markdownlint`
+
+`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases)) are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices must be made when selecting Markdown syntax for GitLab documentation and this tool helps catch deviations from those guidelines.
+
+To help ensure the GitLab style guidelines are followed, run `markdownlint` [from the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--) or add it to your text editor using a plugin. For example:
+
+- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
+- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+- [Others](https://github.com/DavidAnson/markdownlint#related)
+
+NOTE: **Note:**
+There are several utilities that can perform "Markdown linting", from different authors written in different programming languages. Therefore, your choice of which to use depends personal preference.
+
+#### Sample `markdownlint` configuration
+
+The following sample `markdownlint` configuration modifies the available default rules to:
+
+- Adhere to the [style guidelines](styleguide.md).
+- Apply conventions found in the GitLab documentation.
+
+```json
+{
+  "default": true,
+  "header-style": { "style": "atx" },
+  "ul-style": { "style": "dash" },
+  "line-length": false,
+  "no-trailing-punctuation": false,
+  "ol-prefix": { "style": "one" },
+  "hr-style": { "style": "---" },
+  "fenced-code-language": false
+}
+```
+
+NOTE: **Note:**
+This [configuration](https://github.com/DavidAnson/markdownlint/blob/master/schema/markdownlint-config-schema.json) is suitable for [a specific `markdownlint`](https://github.com/DavidAnson/markdownlint/), but can be adapted to suit other tools.
+
 ## Testing
 
 We treat documentation as code, thus have implemented some testing.
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 8083f219d4a..0e3f47a5616 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -10,6 +10,8 @@ GitLab documentation. Check the
 
 Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
 
+For help adhering to the guidelines, see [Linting](index.md#linting).
+
 ## Files
 
 - [Directory structure](index.md#location-and-naming-documents): place the docs