Commit fca17472 authored by Marcia Ramos's avatar Marcia Ramos

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
parents 30209219 4671cb78
...@@ -62,7 +62,7 @@ with files organized in the [correct directory](index.md#documentation-directory ...@@ -62,7 +62,7 @@ with files organized in the [correct directory](index.md#documentation-directory
link out to their external sites, documentation, and resources. link out to their external sites, documentation, and resources.
- Do not duplicate information. - Do not duplicate information.
- Structure content in alphabetical order in tables, lists, etc., unless there is - 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 ## Language
...@@ -210,7 +210,7 @@ For other punctuation rules, please refer to the ...@@ -210,7 +210,7 @@ For other punctuation rules, please refer to the
- Use inline link markdown markup `[Text](https://example.com)`. - Use inline link markdown markup `[Text](https://example.com)`.
It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. 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 - 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`. end of the link with the `.md` extension, not `.html`.
Example: instead of `[text](../../merge_requests/)`, use Example: instead of `[text](../../merge_requests/)`, use
`[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or, `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or,
...@@ -386,8 +386,32 @@ Which renders to: ...@@ -386,8 +386,32 @@ Which renders to:
## Specific sections and terms ## Specific sections and terms
To mention and/or reference specific terms in GitLab, please follow the styles To maintain consistency through GitLab documentation, the following guides documentation authors
below. 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 ### GitLab versions and tiers
...@@ -460,6 +484,10 @@ the special markup `**[STARTER]**` will generate a `span` element to trigger the ...@@ -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 badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
"only" is added, the corresponding GitLab.com badge will not be displayed. "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 ### GitLab Restart
There are many cases that a restart/reconfigure of GitLab is required. To There are many cases that a restart/reconfigure of GitLab is required. To
...@@ -536,13 +564,64 @@ the style below as a guide: ...@@ -536,13 +564,64 @@ the style below as a guide:
In this case: 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 - 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 - The code blocks are indented one or more spaces under the list item to render
correctly correctly.
- Different highlighting languages are used for each config in the code block - Different highlighting languages are used for each config in the code block.
- The [references](#references) guide is used for reconfigure/restart - 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 ### Fake tokens
...@@ -553,7 +632,7 @@ low. ...@@ -553,7 +632,7 @@ low.
You can use the following fake tokens as examples. You can use the following fake tokens as examples.
| **Token type** | **Token value** | | Token type | Token value |
|:----------------------|:-------------------------------------------------------------------| |:----------------------|:-------------------------------------------------------------------|
| Private user token | `<your_access_token>` | | Private user token | `<your_access_token>` |
| Personal access token | `n671WNGecHugsdEDPsyo` | | Personal access token | `n671WNGecHugsdEDPsyo` |
...@@ -567,23 +646,7 @@ You can use the following fake tokens as examples. ...@@ -567,23 +646,7 @@ You can use the following fake tokens as examples.
| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | | Health check token | `Tu7BgjR9qeZTEyRzGG2P` |
| Request profile token | `7VgpS4Ax5utVD2esNstz` | | Request profile token | `7VgpS4Ax5utVD2esNstz` |
### API ### Method description
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
Use the following table headers to describe the methods. Attributes should Use the following table headers to describe the methods. Attributes should
always be in code blocks using backticks (``` ` ```). always be in code blocks using backticks (``` ` ```).
...@@ -599,7 +662,7 @@ Rendered example: ...@@ -599,7 +662,7 @@ Rendered example:
|:----------|:-------|:---------|:--------------------| |:----------|:-------|:---------|:--------------------|
| `user` | string | yes | The GitLab username | | `user` | string | yes | The GitLab username |
#### cURL commands ### cURL commands
- Use `https://gitlab.example.com/api/v4/` as an endpoint. - Use `https://gitlab.example.com/api/v4/` as an endpoint.
- Wherever needed use this personal access token: `<your_access_token>`. - Wherever needed use this personal access token: `<your_access_token>`.
...@@ -616,11 +679,11 @@ Rendered example: ...@@ -616,11 +679,11 @@ Rendered example:
| `-X PUT` | Use this method when updating existing objects | | `-X PUT` | Use this method when updating existing objects |
| `-X DELETE` | Use this method when removing 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. 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: Get the details of a group:
...@@ -628,7 +691,7 @@ 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 --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: Create a new project under the authenticated user's namespace:
...@@ -636,7 +699,7 @@ 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" 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 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 cURL's `--data` option. The example below will create a new project `foo` under
...@@ -646,7 +709,7 @@ the authenticated user's namespace. ...@@ -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" 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 > **Note:** In this example we create a new group. Watch carefully the single
and double quotes. and double quotes.
...@@ -655,7 +718,7 @@ 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 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 Instead of using JSON or urlencode you can use multipart/form-data which
properly handles data encoding: properly handles data encoding:
...@@ -667,7 +730,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title= ...@@ -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 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. 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 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 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 ...@@ -680,7 +743,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
Use `%2F` for slashes (`/`). 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 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 restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment