improve headers (doc structure)

1 files changed, 8 insertions, 6 deletions

diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index f5a543c4201..90cfb28b1ef 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -8,7 +8,7 @@
 
 All the docs follow the same [styleguide](doc_styleguide.md).
 
-### Contributing to docs
+## Contributing to docs
 
 Whenever a feature is changed, updated, introduced, or deprecated, the merge
 request introducing these changes must be accompanied by the documentation
@@ -57,19 +57,21 @@ and for every **major** feature present in Community Edition.
 
 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.
 
-### Testing
+### Previewing locally
 
 To preview your changes to documentation locally, please follow
 this [development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development).
 
+### Testing
+
 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. It's recommended
-   to check locally before pushing to GitLab by executing the command
+   to [check locally](#previewing-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.
+   [`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)
@@ -154,12 +156,12 @@ working on. If you don't, the remote docs branch won't be removed either,
 and the server where the Review Apps are hosted will eventually be out of
 disk space.
 
-### Behind the scenes
+#### Behind the scenes
 
 If you want to know the hot details, here's what's really happening:
 
 1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
-1. The job runs the [`scirpts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
+1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
    script with the `deploy` flag, which in turn:
    1. Takes your branch name and applies the following:
       - The slug of the branch name is used to avoid special characters since