1 files changed, 41 insertions, 18 deletions
diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md
index 9934d543991..56200142055 100644
--- a/doc/ci/enable_or_disable_ci.md
+++ b/doc/ci/enable_or_disable_ci.md
@@ -1,29 +1,32 @@
 ---
-type: reference
+type: howto
 ---
 
 # How to enable or disable GitLab CI/CD
 
-To effectively use GitLab CI/CD, you need a valid [`.gitlab-ci.yml`](yaml/README.md)
-file present at the root directory of your project and a
-[runner](runners/README.md) properly set up. You can read our
-[quick start guide](quick_start/README.md) to get you started.
+To effectively use GitLab CI/CD, you need:
+
+- A valid [`.gitlab-ci.yml`](yaml/README.md) file present at the root directory
+  of your project.
+- A [runner](runners/README.md) properly set up.
+
+You can read our [quick start guide](quick_start/README.md) to get you started.
 
 If you are using an external CI/CD server like Jenkins or Drone CI, it is advised
 to disable GitLab CI/CD in order to not have any conflicts with the commits status
 API.
 
----
-
 GitLab CI/CD is exposed via the `/pipelines` and `/jobs` pages of a project.
 Disabling GitLab CI/CD in a project does not delete any previous jobs.
 In fact, the `/pipelines` and `/jobs` pages can still be accessed, although
 it's hidden from the left sidebar menu.
 
-GitLab CI/CD is enabled by default on new installations and can be disabled either
-individually under each project's settings, or site-wide by modifying the
-settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations
-respectively.
+GitLab CI/CD is enabled by default on new installations and can be disabled
+either:
+
+- Individually under each project's settings.
+- Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source
+  and Omnibus installations respectively.
 
 ## Per-project user setting
 
@@ -40,10 +43,10 @@ and `gitlab.rb` for source and Omnibus installations respectively.
 
 Two things to note:
 
-1. Disabling GitLab CI/CD, will affect only newly-created projects. Projects that
-   had it enabled prior to this modification, will work as before.
-1. Even if you disable GitLab CI/CD, users will still be able to enable it in the
-   project's settings.
+- Disabling GitLab CI/CD, will affect only newly-created projects. Projects that
+  had it enabled prior to this modification, will work as before.
+- Even if you disable GitLab CI/CD, users will still be able to enable it in the
+  project's settings.
 
 For installations from source, open `gitlab.yml` with your editor and set
 `builds` to `false`:
@@ -58,12 +61,32 @@ default_projects_features:
   builds: false
 ```
 
-Save the file and restart GitLab: `sudo service gitlab restart`.
+Save the file and restart GitLab:
+
+```sh
+sudo service gitlab restart
+```
 
 For Omnibus installations, edit `/etc/gitlab/gitlab.rb` and add the line:
 
-```
+```ruby
 gitlab_rails['gitlab_default_projects_features_builds'] = false
 ```
 
-Save the file and reconfigure GitLab: `sudo gitlab-ctl reconfigure`.
+Save the file and reconfigure GitLab:
+
+```sh
+sudo gitlab-ctl reconfigure
+```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->