improve documentation "testing" section

1 files changed, 19 insertions, 13 deletions

diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index b6def7ef541..e6f4b0efe99 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -120,11 +120,27 @@ Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, b
 
 ## Testing
 
-We try to treat documentation as code, thus have implemented some testing.
+To preview your changes to documentation locally, please follow
+this [development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development).
+
+We treat documentation as code, thus have implemented some testing.
 Currently, the following tests are in place:
 
 1. `docs lint`: Check that all internal (relative) links work correctly and
-   that all cURL examples in API docs use the full switches.
+   that all cURL examples in API docs use the full switches. It's recommended
+   to check locally before pushing to GitLab by executing the command
+   `bundle exec nanoc check internal_links` on your local
+   [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
+1. [`ee_compat_check`](https://docs.gitlab.com/ee/development/automatic_ce_ee_merge.html#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
+    When you submit a merge request to GitLab Community Edition (CE),
+    there is this additional job that runs against Enterprise Edition (EE)
+    and checks if your changes can apply cleanly to the EE codebase.
+    If that job fails, read the instructions in the job log for what to do next.
+    As CE is merged into EE once a day, it's important to avoid merge conflicts.
+    Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
+    essential to avoid them.
+
+### Branch naming
 
 If your contribution contains **only** documentation changes, you can speed up
 the CI process by following some branch naming conventions. You have three
@@ -139,16 +155,6 @@ 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).
 
----
-
-When you submit a merge request to GitLab Community Edition (CE), there is an
-additional job called `rake ee_compat_check` that runs against Enterprise
-Edition (EE) and checks if your changes can apply cleanly to the EE codebase.
-If that job fails, read the instructions in the job log for what to do next.
-Contributors do not need to submit their changes to EE, GitLab Inc. employees
-on the other hand need to make sure that their changes apply cleanly to both
-CE and EE.
-
 ## Previewing the changes live
 
 If you want to preview the doc changes of your merge request live, you can use
@@ -164,7 +170,7 @@ You will need to push a branch to those repositories, it doesn't work for forks.
 
 TIP: **Tip:**
 If your branch contains only documentation changes, you can use
-[special branch names](#testing) to avoid long running pipelines.
+[special branch names](#branch-naming) to avoid long running pipelines.
 
 In the mini pipeline graph, you should see an `>>` icon. Clicking on it will
 reveal the `review-docs-deploy` job. Hit the play button for the job to start.