Implement some review comments

Also:

- Slight restructure.
- Some Markdown improvements.

doc/development/documentation/styleguide.md

@@ -62,7 +62,7 @@ with files organized in the [correct directory](index.md#documentation-directory
   link out to their external sites, documentation, and resources.
 - Do not duplicate information.
 - Structure content in alphabetical order in tables, lists, etc., unless there is
-a logical reason not to (for example, when mirroring the UI or an ordered sequence). 
+a logical reason not to (for example, when mirroring the UI or an ordered sequence).
 
 ## Language
 
@@ -398,20 +398,20 @@ The following are styles to follow when describing UI elements on a screen:
 
 ### Verbs for UI elements
 
-The following are verbs that should be used in preference to alternatives.
+The following are recommended verbs for specific uses.
 
-| Use      | Used for                        | Do not use                 |
-|:---------|:--------------------------------|:---------------------------|
-| "click"  | buttons, links, menu items      | "hit", "press", "select"   |
-| "check"  | checkboxes                      | "enable", "click", "press" |
-| "select" | dropdowns                       | "pick"                     |
-| "expand" | expandable sections             | "open"                     |
+| Recommended | Used for                   | Alternatives               |
+|:------------|:---------------------------|:---------------------------|
+| "click"     | buttons, links, menu items | "hit", "press", "select"   |
+| "check"     | checkboxes                 | "enable", "click", "press" |
+| "select"    | dropdowns                  | "pick"                     |
+| "expand"    | expandable sections        | "open"                     |
 
 ### Other Verbs
 
-| Use      | Used for                        | Do not use                 |
-|:---------|:--------------------------------|:---------------------------|
-| "go"     | making a browser go to location | "navigate", "open"         |
+| Recommended | Used for                        | Alternatives       |
+|:------------|:--------------------------------|:-------------------|
+| "go"        | making a browser go to location | "navigate", "open" |
 
 ### GitLab versions and tiers
 
@@ -564,13 +564,29 @@ the style below as a guide:
 
 In this case:
 
-- Before each step list the installation method is declared in bold
+- Before each step list the installation method is declared in bold.
 - Three dashes (`---`) are used to create a horizontal line and separate the
-  two methods
+  two methods.
 - The code blocks are indented one or more spaces under the list item to render
-  correctly
-- Different highlighting languages are used for each config in the code block
-- The [references](#references) guide is used for reconfigure/restart
+  correctly.
+- Different highlighting languages are used for each config in the code block.
+- The [references](#references) guide is used for reconfigure/restart.
+
+## API
+
+Here is a list of must-have items. Use them in the exact order that appears
+on this document. Further explanation is given below.
+
+- Every method must have the REST API request. For example:
+
+    ```
+    GET /projects/:id/repository/branches
+    ```
+
+- Every method must have a detailed
+  [description of the parameters](#method-description).
+- Every method must have a cURL example.
+- Every method must have a response body (in JSON format).
 
 ### Fake tokens
 
@@ -581,7 +597,7 @@ low.
 
 You can use the following fake tokens as examples.
 
-| **Token type**        | **Token value**                                                    |
+| Token type            | Token value                                                        |
 |:----------------------|:-------------------------------------------------------------------|
 | Private user token    | `<your_access_token>`                                             |
 | Personal access token | `n671WNGecHugsdEDPsyo`                                             |
@@ -595,23 +611,7 @@ You can use the following fake tokens as examples.
 | Health check token    | `Tu7BgjR9qeZTEyRzGG2P`                                             |
 | Request profile token | `7VgpS4Ax5utVD2esNstz`                                             |
 
-### API
-
-Here is a list of must-have items. Use them in the exact order that appears
-on this document. Further explanation is given below.
-
-- Every method must have the REST API request. For example:
-
-    ```
-    GET /projects/:id/repository/branches
-    ```
-
-- Every method must have a detailed
-  [description of the parameters](#method-description).
-- Every method must have a cURL example.
-- Every method must have a response body (in JSON format).
-
-#### Method description
+### Method description
 
 Use the following table headers to describe the methods. Attributes should
 always be in code blocks using backticks (``` ` ```).
@@ -627,7 +627,7 @@ Rendered example:
 |:----------|:-------|:---------|:--------------------|
 | `user`    | string | yes      | The GitLab username |
 
-#### cURL commands
+### cURL commands
 
 - Use `https://gitlab.example.com/api/v4/` as an endpoint.
 - Wherever needed use this personal access token: `<your_access_token>`.
@@ -644,11 +644,11 @@ Rendered example:
 | `-X PUT`                                   | Use this method when updating existing objects        |
 | `-X DELETE`                                | Use this method when removing existing objects        |
 
-#### cURL Examples
+### cURL Examples
 
 Below is a set of [cURL][] examples that you can use in the API documentation.
 
-##### Simple cURL command
+#### Simple cURL command
 
 Get the details of a group:
 
@@ -656,7 +656,7 @@ Get the details of a group:
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/gitlab-org
 ```
 
-##### cURL example with parameters passed in the URL
+#### cURL example with parameters passed in the URL
 
 Create a new project under the authenticated user's namespace:
 
@@ -664,7 +664,7 @@ Create a new project under the authenticated user's namespace:
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?name=foo"
 ```
 
-##### Post data using cURL's --data
+#### Post data using cURL's --data
 
 Instead of using `-X POST` and appending the parameters to the URI, you can use
 cURL's `--data` option. The example below will create a new project `foo` under
@@ -674,7 +674,7 @@ the authenticated user's namespace.
 curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
 ```
 
-##### Post data using JSON content
+#### Post data using JSON content
 
 > **Note:** In this example we create a new group. Watch carefully the single
 and double quotes.
@@ -683,7 +683,7 @@ and double quotes.
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups
 ```
 
-##### Post data using form-data
+#### Post data using form-data
 
 Instead of using JSON or urlencode you can use multipart/form-data which
 properly handles data encoding:
@@ -695,7 +695,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=
 The above example is run by and administrator and will add an SSH public key
 titled ssh-key to user's account which has an id of 25.
 
-##### Escape special characters
+#### Escape special characters
 
 Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
 to escape them when possible. In the example below we create a new issue which
@@ -708,7 +708,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
 
 Use `%2F` for slashes (`/`).
 
-##### Pass arrays to API calls
+#### Pass arrays to API calls
 
 The GitLab API sometimes accepts arrays of strings or integers. For example, to
 restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and