diff options
author | Marcia Ramos <marcia@gitlab.com> | 2019-01-07 15:17:06 +0300 |
---|---|---|
committer | Marcia Ramos <marcia@gitlab.com> | 2019-01-07 15:17:06 +0300 |
commit | fca174722c2c859ce6ef6c7cbbfeea3c7d1d7f74 (patch) | |
tree | a45cb2b73c4267bc4a7eb2296b39239e9a16b6fe /doc | |
parent | 30209219a4327aa8614c937ac1de0ab5566b2599 (diff) | |
parent | 4671cb7836d9269bd965be946dd9d62fc7e1ddef (diff) |
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
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/documentation/styleguide.md | 135 |
1 files changed, 99 insertions, 36 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 829dcf18926..a18c21d921a 100644 --- a/doc/development/documentation/styleguide.md +++ b/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 |