3 files changed, 194 insertions, 48 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index f46c171d9f1..2db78e4a365 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,108 @@ 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 locally installing and running documentation linters. This will
+ help you catch common issues before raising merge requests for review of documentation.
+
+The following are some suggested linters you can install locally and sample configuration:
+
+- `proselint`
+- `markdownlint`
+
+NOTE: **Note:**
+This list does not limit what other linters you can add to your local 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/), either on a single
+ Markdown file or on all Markdown files in a project. For example, to run `proselint` on all
+ documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), run the
+ following commands from within the `gitlab-ce` project:
+
+```sh
+cd doc
+proselint **/*.md
+```
+
+`proselint` can also be run from within editors using plugins. For example, the following plugins
+ are available:
+
+- [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
+  }
+}
+```
+
+A file with `proselint` configuration must be placed in a
+ [valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
+
+### `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.
+
+`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
+ either on a single Markdown file or on all Markdown files in a project. For example, to run
+ `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
+ run the following commands from within the `gitlab-ce` project:
+
+```sh
+cd doc
+markdownlint **/*.md
+```
+
+`markdownlint` can also be run from within editors using plugins. For example, the following plugins
+ are available:
+
+- [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)
+
+#### 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" },
+  "blanks-around-fences": false,
+  "hr-style": { "style": "---" },
+  "fenced-code-language": false
+}
+```
+
+For [`markdownlint`](https://gitahub.com/DavidAnson/markdownlint/), this configuration must be
+ placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
+ example, `~/.markdownlintrc`.
+
 ## Testing
 
 We treat documentation as code, thus have implemented some testing.
@@ -257,6 +359,15 @@ choices:
 If your branch name matches any of the above, it will run only the docs
 tests. If it doesn't, the whole test suite will run (including docs).
 
+## Danger bot
+
+GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
+code review. For docs changes in merge requests, the following actions are taken:
+
+1. Whenever a change under `/doc` is made, the bot leaves a comment for the
+   author to mention `@gl-docsteam`, so that the docs can be properly
+   reviewed.
+
 ## Merge requests for GitLab documentation
 
 Before getting started, make sure you read the introductory section
@@ -269,7 +380,6 @@ for GitLab Team members.
 - Label the MR `Documentation`
 - Assign the correct milestone (see note below)
 
-
 NOTE: **Note:**
 If the release version you want to add the documentation to has already been
 frozen or released, use the label `Pick into X.Y` to get it merged into
@@ -402,6 +512,22 @@ The following GitLab features are used among others:
 Every GitLab instance includes the documentation, which is available from `/help`
 (`http://my-instance.com/help`), e.g., <https://gitlab.com/help>.
 
+The documentation available online on docs.gitlab.com is continuously
+deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore,
+once a merge request gets merged, it will be available online on the same day,
+but they will be shipped (and available on `/help`) within the milestone assigned
+to the MR.
+
+For instance, let's say your merge request has a milestone set to 11.3, which
+will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be
+available online on 2018-09-15, but, as the feature freeze date has passed, if
+the MR does not have a "pick into 11.3" label, the milestone has to be changed
+to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22,
+with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab
+11.4 onwards, but available on docs.gitlab.com on the same day it was merged.
+
+### Linking to `/help`
+
 When you're building a new feature, you may need to link the documentation
 from GitLab, the application. This is normally done in files inside the
 `app/views/` directory with the help of the `help_page_path` helper method.
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 6c60a517b6d..c43f91278de 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -10,13 +10,15 @@ 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
-in the correct location
-- [Documentation files](index.md#documentation-files): name the files accordingly
+in the correct location.
+- [Documentation files](index.md#documentation-files): name the files accordingly.
 - [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
-documentation
+documentation.
 
 NOTE: **Note:**
 **Do not** use capital letters, spaces, or special chars in file names,
@@ -30,17 +32,17 @@ a test that will fail if it spots a new `README.md` file.
 
 - Split up long lines (wrap text), this makes it much easier to review and edit. Only
   double line breaks are shown as a full line break in [GitLab markdown][gfm].
-  80-100 characters is a good line length
+  80-100 characters is a good line length.
 - Make sure that the documentation is added in the correct
   [directory](index.md#documentation-directory-structure) and that
-  there's a link to it somewhere useful
-- Do not duplicate information
-- Be brief and clear
-- Unless there's a logical reason not to, add documents in alphabetical order
-- Write in US English
-- Use [single spaces][] instead of double spaces
+  there's a link to it somewhere useful.
+- Do not duplicate information.
+- Be brief and clear.
+- Unless there's a logical reason not to, add documents in alphabetical order.
+- Write in US English.
+- Use [single spaces][] instead of double spaces.
 - Jump a line between different markups (e.g., after every paragraph, header, list, etc)
-- Capitalize "G" and "L" in GitLab
+- Capitalize "G" and "L" in GitLab.
 - Use sentence case for titles, headings, labels, menu items, and buttons.
 - Use title case when referring to [features](https://about.gitlab.com/features/) or
 [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
@@ -50,10 +52,9 @@ some features are also objects (e.g. "Merge Requests" and "merge requests").
 
 ## Formatting
 
-- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`)
-- Use undescore (`_`) for text in italics (`_italic_`)
-- Jump a line between different markups, for example:
-
+- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
+- Use undescore (`_`) for text in italics (`_italic_`).
+- Put an empty line between different markups. For example:
     ```md
     ## Header
 
@@ -69,9 +70,16 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
 
 ### Ordered and unordered lists
 
-- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
-- Use the number one (`1`) for ordered lists
-- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/)
+- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
+- Use the number one (`1`) for ordered lists.
+- Separate list items from explanatory text with a colon (`:`). For example:
+    ```md
+    The list is as follows:
+
+    - First item: This explains the first item.
+    - Second item: This explains the second item.
+    ```
+- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
 
 ## Headings
 
@@ -82,7 +90,7 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
 - Avoid putting numbers in headings. Numbers shift, hence documentation anchor
   links shift too, which eventually leads to dead links. If you think it is
   compelling to add numbers in headings, make sure to at least discuss it with
-  someone in the Merge Request
+  someone in the Merge Request.
 - [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84)
   in headers. Whenever possible, they should be plain and short text.
 - Avoid adding things that show ephemeral statuses. For example, if a feature is
@@ -92,8 +100,8 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
   of the following GitLab members for a review: `@axil` or `@marcia`.
   This is to ensure that no document with wrong heading is going
   live without an audit, thus preventing dead links and redirection issues when
-  corrected
-- Leave exactly one new line after a heading
+  corrected.
+- Leave exactly one new line after a heading.
 
 ## Links
 
@@ -120,11 +128,11 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
 
 To indicate the steps of navigation through the UI:
 
-- Use the exact word as shown in the UI, including any capital letters as-is
+- Use the exact word as shown in the UI, including any capital letters as-is.
 - Use bold text for navigation items and the char `>` as separator
-(e.g., `Navigate to your project's **Settings > CI/CD**` )
+(e.g., `Navigate to your project's **Settings > CI/CD**` ).
 - If there are any expandable menus, make sure to mention that the user
-needs to expand the tab to find the settings you're referring to
+needs to expand the tab to find the settings you're referring to.
 
 ## Images
 
@@ -149,12 +157,12 @@ Inside the document:
   `![Proper description what the image is about](img/document_image_title.png)`
 - Always use a proper description for what the image is about. That way, when a
   browser fails to show the image, this text will be used as an alternative
-  description
+  description.
 - If there are consecutive images with little text between them, always add
   three dashes (`---`) between the image and the text to create a horizontal
-  line for better clarity
+  line for better clarity.
 - If a heading is placed right after an image, always add three dashes (`---`)
-  between the image and the heading
+  between the image and the heading.
 
 ## Alert boxes
 
@@ -245,7 +253,7 @@ below.
   (in that order) that introduced it. The above quote would be then transformed to:
 
     ```md
-    > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) in GitLab 8.3.
+    > [Introduced](<link-to-issue>) in GitLab 8.3.
     ```
 
 - If the feature is only available in GitLab Enterprise Edition, don't forget to mention
@@ -253,27 +261,39 @@ below.
   the feature is available in:
 
     ```md
-    > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242)
-    in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+    > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
     ```
 
+#### Early versions of EE
+
+If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)):
+
+- Declare it as "Introduced in GitLab Enterprise Edition X.Y".
+- Note which tier the feature is available in.
+
+For example:
+
+```md
+> [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/).
+```
+
 ### Product badges
 
 When a feature is available in EE-only tiers, add the corresponding tier according to the
 feature availability:
 
-- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`
-- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`
-- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`
-- For GitLab Core and GitLab.com Free: `**[CORE]**`
+- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`.
+- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`.
+- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`.
+- For GitLab Core and GitLab.com Free: `**[CORE]**`.
 
 To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
 keyword "only":
 
-- For GitLab Starter: `**[STARTER ONLY]**`
-- For GitLab Premium: `**[PREMIUM ONLY]**`
-- For GitLab Ultimate: `**[ULTIMATE ONLY]**`
-- For GitLab Core: `**[CORE ONLY]**`
+- For GitLab Starter: `**[STARTER ONLY]**`.
+- For GitLab Premium: `**[PREMIUM ONLY]**`.
+- For GitLab Ultimate: `**[ULTIMATE ONLY]**`.
+- For GitLab Core: `**[CORE ONLY]**`.
 
 The tier should be ideally added to headers, so that the full badge will be displayed.
 But it can be also mentioned from paragraphs, list items, and table cells. For these cases,
@@ -297,10 +317,10 @@ avoid duplication, link to the special document that can be found in
 [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
 read like:
 
-  ```
-  Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
-  for the changes to take effect.
-  ```
+```
+Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
+for the changes to take effect.
+```
 
 If the document you are editing resides in a place other than the GitLab CE/EE
 `doc/` directory, instead of the relative link, use the full path:
@@ -328,8 +348,8 @@ prefer to document it in the CE docs to avoid duplication.
 
 Configuration settings include:
 
-- settings that touch configuration files in `config/`
-- NGINX settings and settings in `lib/support/` in general
+- Settings that touch configuration files in `config/`.
+- NGINX settings and settings in `lib/support/` in general.
 
 When there is a list of steps to perform, usually that entails editing the
 configuration file and reconfiguring/restarting GitLab. In such case, follow
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 339ec80f889..52bc059a925 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -31,7 +31,7 @@ only and does not directly affect the way that any regular user or
 administrator would interact with GitLab.
 
 NOTE: **Note:**
-When refactoring documentation in needed, it should be submitted it in its own MR.
+When refactoring documentation, it should be submitted in its own MR.
 **Do not** join new features' MRs with refactoring existing docs, as they might have
 different priorities.