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
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
......
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