Merge branch 'docs/new-verbs-section-styleguide' into 'master'

Increase consistency of documentation suite with more guidance

See merge request gitlab-org/gitlab-ce!22249

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
 
@@ -210,7 +210,7 @@ For other punctuation rules, please refer to the
 - Use inline link markdown markup `[Text](https://example.com)`.
   It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
 - To link to internal documentation, use relative links, not full URLs. Use `../` to
-  navigate tp high-level directories, and always add the file name `file.md` at the
+  navigate to high-level directories, and always add the file name `file.md` at the
   end of the link with the `.md` extension, not `.html`.
   Example: instead of `[text](../../merge_requests/)`, use
   `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or,
@@ -386,8 +386,32 @@ Which renders to:
 
 ## Specific sections and terms
 
-To mention and/or reference specific terms in GitLab, please follow the styles
-below.
+To maintain consistency through GitLab documentation, the following guides documentation authors
+on agreed styles and usage of terms.
+
+### Describing UI elements
+
+The following are styles to follow when describing UI elements on a screen:
+
+- For elements with a visible label, use that label in bold with matching case. For example, `the **Cancel** button`.
+- For elements with a tooltip or hover label, use that label in bold with matching case. For example, `the **Add status emoji** button`.
+
+### Verbs for UI elements
+
+The following are recommended verbs for specific uses.
+
+| 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
+
+| Recommended | Used for                        | Alternatives       |
+|:------------|:--------------------------------|:-------------------|
+| "go"        | making a browser go to location | "navigate", "open" |
 
 ### GitLab versions and tiers
 
@@ -460,6 +484,10 @@ the special markup `**[STARTER]**` will generate a `span` element to trigger the
 badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
 "only" is added, the corresponding GitLab.com badge will not be displayed.
 
+## Specific sections
+
+Certain styles should be applied to specific sections. Styles for specific sections are outlined below.
+
 ### GitLab Restart
 
 There are many cases that a restart/reconfigure of GitLab is required. To
@@ -536,13 +564,64 @@ 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).
+
+### API topic template
+
+The following can be used as a template to get started:
+
+```md
+## Descriptive title
+
+One or two sentence description of what endpoint does.
+
+```
+METHOD /endpoint
+```
+
+| Attribute   | Type     | Required | Description           |
+|:------------|:---------|:---------|:----------------------|
+| `attribute` | datatype | yes/no   | Detailed description. |
+| `attribute` | datatype | yes/no   | Detailed description. |
+
+Example request:
+
+```sh
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/endpoint?parameters'
+```
+
+Example response:
+
+```json
+[
+  {
+  }
+]
+```
+
+```
 
 ### Fake tokens
 
@@ -553,7 +632,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`                                             |
@@ -567,23 +646,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 (``` ` ```).
@@ -599,7 +662,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>`.
@@ -616,11 +679,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:
 
@@ -628,7 +691,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:
 
@@ -636,7 +699,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
@@ -646,7 +709,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.
@@ -655,7 +718,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:
@@ -667,7 +730,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
@@ -680,7 +743,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