diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/img/manual_build_docs_v14_3.png | bin | 14855 -> 0 bytes | |||
| -rw-r--r-- | doc/development/documentation/img/manual_build_docs_v14_6.png | bin | 0 -> 26853 bytes | |||
| -rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 45 | ||||
| -rw-r--r-- | doc/development/documentation/review_apps.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/deployment_process.md | 8 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/img/callouts.png | bin | 0 -> 4875 bytes | |||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 56 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 311 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 100 |
11 files changed, 370 insertions, 158 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 8fc6f2e2641..6a618e47211 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -58,7 +58,7 @@ FLAG: If needed, you can add this sentence: -`You should not use this feature for production environments.` +`The feature is not ready for production use.` ## Add version history text @@ -109,7 +109,7 @@ And, when the feature is done and fully available to all users: ```markdown > - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. -> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. +> - [Enabled on self-managed](https://gitlab.com/issue/etc) in GitLab 13.8. > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. > - [Generally available](issue-link) in GitLab 14.0. [Feature flag <flag name>](issue-link) removed. ``` diff --git a/doc/development/documentation/img/manual_build_docs_v14_3.png b/doc/development/documentation/img/manual_build_docs_v14_3.png Binary files differdeleted file mode 100644 index e366a2f7ec4..00000000000 --- a/doc/development/documentation/img/manual_build_docs_v14_3.png +++ /dev/null diff --git a/doc/development/documentation/img/manual_build_docs_v14_6.png b/doc/development/documentation/img/manual_build_docs_v14_6.png Binary files differnew file mode 100644 index 00000000000..731bda3dd56 --- /dev/null +++ b/doc/development/documentation/img/manual_build_docs_v14_6.png diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 03980a42381..5dc627c93e9 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -1,9 +1,6 @@ --- -type: reference, dev -stage: none -group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" -description: "Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs." +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.' --- # RESTful API @@ -30,6 +27,10 @@ In the Markdown doc for a resource (AKA endpoint): - 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). +- If an attribute is available only to higher level tiers than the other + parameters, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges). + Put the badge in the **Attribute** column, like the + `**(<tier>)**` code in the following template. ## API topic template @@ -49,12 +50,12 @@ METHOD /endpoint Supported attributes: -| Attribute | Type | Required | Description | -| :---------- | :------- | :--------------------- | :-------------------- | -| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | -| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | -| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | -| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| Attribute | Type | Required | Description | +|:-------------------------|:---------|:-----------------------|:----------------------| +| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | +| `attribute` **(<tier>)** | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | Example request: @@ -83,20 +84,20 @@ always be in code blocks using backticks (`` ` ``). Sort the attributes in the table: first, required, then alphabetically. ```markdown -| Attribute | Type | Required | Description | -| :------------- | :------------ | :--------------------- | :--------------------------------------------------- | -| `user` | string | **{check-circle}** Yes | The GitLab username. | -| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | +| Attribute | Type | Required | Description | +|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------| +| `user` | string | **{check-circle}** Yes | The GitLab username. | +| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | ``` Rendered example: -| Attribute | Type | Required | Description | -| :------------- | :------------ | :--------------------- | :--------------------------------------------------- | -| `user` | string | **{check-circle}** Yes | The GitLab username. | -| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | +| Attribute | Type | Required | Description | +|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------| +| `user` | string | **{check-circle}** Yes | The GitLab username. | +| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | ## cURL commands @@ -109,7 +110,7 @@ Rendered example: username and password. | Methods | Description | -| :---------------------------------------------- | :----------------------------------------------------- | +|:------------------------------------------------|:-------------------------------------------------------| | `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. | | `--request POST` | Use this method when creating new objects | | `--request PUT` | Use this method when updating existing objects | diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index a5094ea87f0..4b58778a20c 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -26,7 +26,7 @@ to render and preview the documentation locally. If a merge request has documentation changes, use the `review-docs-deploy` manual job to deploy the documentation review app for your merge request. - + The `review-docs-deploy*` job triggers a cross project pipeline and builds the docs site with your changes. When the pipeline finishes, the review app URL diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index c038ee96dbf..25bc699c9d4 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -50,8 +50,8 @@ that stable documentation and deploys it to the registry. For example: - [13.12 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/395365202). - [12.10 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/395365405). -In particular, the [`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L655) in each pipeline -takes what is built, and pushes it to the [container registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635). +In particular, the [`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L655) in each pipeline runs automatically. +It takes what is built, and pushes it to the [container registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635). ```mermaid graph TD @@ -91,6 +91,7 @@ The [`image:docs-latest` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4 - Pulls the latest documentation from the default branches of the relevant upstream projects. - Pulls the Docker images previously built by the `image:docs-single` jobs. +- Must be run manually on a scheduled pipeline. For example, [a pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/399233948) containing the [`image:docs-latest` job](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/1733948330): @@ -122,7 +123,8 @@ graph TD for it must be deployed to become available. The [`pages`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L491) -job runs the necessary commands to combine: +job runs automatically when a pipeline runs on the default branch (`main`). +It runs the necessary commands to combine: - A very up-to-date build of the `gitlab-docs` site code. - The latest docs from the default branches of the upstream projects. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index fac83af89f4..6ecffce01b4 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -88,7 +88,7 @@ Create an issue when you want to track bugs or future work. Prerequisites: -- You must have at least the Developer role for a project. +- You must have at least the Developer role for the project. To create an issue: diff --git a/doc/development/documentation/styleguide/img/callouts.png b/doc/development/documentation/styleguide/img/callouts.png Binary files differnew file mode 100644 index 00000000000..b84e9e269dc --- /dev/null +++ b/doc/development/documentation/styleguide/img/callouts.png diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 1382ec263f2..7f2e5a1ba26 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -58,8 +58,7 @@ it was originally composed for, if it is helpful to any of our audiences, we can include it. - If you use an image that has a separate source file (for example, a vector or - diagram format), link the image to the source file so that it may be reused or - updated by anyone. + diagram format), link the image to the source file so that anyone can update or reuse it. - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. @@ -113,8 +112,9 @@ The more we reflexively add information to the documentation, the more the documentation helps others efficiently accomplish tasks and solve problems. If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team. They're available on Slack in `#docs` or in GitLab by mentioning the -writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). +the Technical Writing team. They're available on Slack in `#docs` or in GitLab by +mentioning [the writer for](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) +the applicable [DevOps stage or group](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Review the [Documentation guidelines](index.md) before you begin your first documentation MR. @@ -787,10 +787,13 @@ This is overridden by the [documentation-specific punctuation rules](#punctuatio - When possible, avoid including words that might change in the future. Changing a heading changes its anchor URL, which affects other linked pages. - When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/categories/) - for review. + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) + for review, based upon the [product category](https://about.gitlab.com/handbook/product/categories/). This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when corrected. +- Use the context provided by parent section headings. That is, don't repeat the parent heading's text in each + subsection's heading. +- Use articles and prepositions in headings where it would make sense in regular text. - Leave exactly one blank line before and after a heading. - Do not use links in headings. - Add the corresponding [product badge](#product-tier-badges) according to the tier the @@ -1053,7 +1056,9 @@ Guidance for each individual UI element is in [the word list](word_list.md). ### How to write navigation task steps -To be consistent, use this format when you write navigation steps in a task topic. +To be consistent, use these templates when you write navigation steps in a task topic. + +To open project settings: ```markdown 1. On the top bar, select **Menu > Projects** and find your project. @@ -1061,7 +1066,7 @@ To be consistent, use this format when you write navigation steps in a task topi 1. Expand **General pipelines**. ``` -Another example: +To open group settings: ```markdown 1. On the top bar, select **Menu > Groups** and find your group. @@ -1069,7 +1074,7 @@ Another example: 1. Expand **General pipelines**. ``` -An Admin Area example: +To open the Admin Area: ```markdown 1. On the top bar, select **Menu > Admin**. @@ -1081,6 +1086,15 @@ To select your avatar: 1. On the top bar, in the top right corner, select your avatar. ``` +To save the selection in some dropdown lists: + +```markdown +1. Go to your issue. +1. On the right sidebar, in the **Iteration** section, select **Edit**. +1. From the dropdown list, select the iteration to associate this issue with. +1. Select any area outside the dropdown list. +``` + ### Optional steps If a step is optional, start the step with the word `Optional` followed by a period. @@ -1150,6 +1164,17 @@ review app in the merge request. Make sure the image isn't blurry or overwhelmin - **Be consistent.** Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience. +### Add callouts + +If you need to emphasize an area in a screenshot, use an arrow. + +- For color, use `#EE2604`. If you use the Preview application on macOS, this is the default red. +- For the line width, use 3 pt. If you use the Preview application on macOS, this is the third line in the list. +- Use the arrow style shown in the following image. +- If you have multiple arrows, make them parallel when possible. + + + ### Save the image - Resize any wide or tall screenshots if needed, but make sure the screenshot is @@ -1575,7 +1600,7 @@ users be aware of recent improvements or additions. The GitLab Technical Writing team determines which versions of documentation to display on this site based on the GitLab -[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#we-support-the-current-major-version-and-the-two-previous-major-versions). +[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#version-support). ### View older GitLab documentation versions @@ -1628,6 +1653,13 @@ This feature does something. This feature does something else. ``` +If you're documenting elements of a feature, start with the feature name or a gerund: + +```markdown +> - Notifications for expiring tokens [introduced](<link-to-issue>) in GitLab 11.3. +> - Creating an issue from an issue board [introduced](<link-to-issue>) in GitLab 13.1. +``` + If a feature is moved to another tier: ```markdown @@ -1781,7 +1813,9 @@ after the heading text. For example: # Heading title **(FREE)** ``` -Do not add tier badges inline with other text. The single source of truth for a feature should be the heading where the functionality is described. +Do not add tier badges inline with other text, except for [API attributes](../restful_api_styleguide.md). +The single source of truth for a feature should be the heading where the +functionality is described. #### Available product tier badges diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 595dab09bf5..9c375379685 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -5,9 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- -# A-Z word list +# Recommended word list -To help ensure consistency in the documentation, follow this guidance. +To help ensure consistency in the documentation, the Technical Writing team +recommends these wording choices. The GitLab handbook also maintains a list of +[top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/). For guidance not on this page, we defer to these style guides: @@ -20,7 +22,7 @@ For guidance not on this page, we defer to these style guides: ## `@mention` Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the -[mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). +[mentions topic](../../../user/discussions/index.md#mentions). Don't use backticks. ## above @@ -31,9 +33,14 @@ Try to avoid using **above** when referring to an example or table in a document Do not use **above** when referring to versions of the product. Use [**later**](#later) instead. -- Do: In GitLab 14.4 and later... -- Do not: In GitLab 14.4 and above... -- Do not: In GitLab 14.4 and higher... +Use: + +- In GitLab 14.4 and later... + +Instead of: + +- In GitLab 14.4 and above... +- In GitLab 14.4 and higher... ## access level @@ -47,16 +54,21 @@ Capitalize these words when you refer to the UI. Otherwise use lowercase. Use **administrator** instead of **admin** when talking about a user's access level. Use lowercase unless you are referring to the **Admin** access level you select in the UI. -To view the administrator access type, in the GitLab UI, go to the Admin Area and select +To view the administrator access level, in the GitLab UI, go to the Admin Area and select **Users**. Then select **New user**.  An **administrator** is not a [role](#roles) or [permission](#permissions). -- Do: To do this thing, you must be an administrator. -- Do: To do this thing, you must have the administrator access level. -- Do not: To do this thing, you must have the Admin role. +Use: + +- To do this thing, you must be an administrator. +- To do this thing, you must have the administrator access level. + +Instead of: + +- To do this thing, you must have the Admin role. ## Admin Area @@ -65,10 +77,16 @@ This area of the UI says **Admin Area** at the top of the page and on the menu. ## allow, enable -Try to avoid **allow** and **enable**, unless you are talking about security-related features. For example: +Try to avoid **allow** and **enable**, unless you are talking about security-related features. -- Do: Use this feature to create a pipeline. -- Do not: This feature allows you to create a pipeline. +Use: + +- You can add a file to your repository. + +Instead of: + +- This feature allows you to add a file to your repository. +- This feature enables users to add files to their repository. This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). @@ -124,8 +142,13 @@ Use **text box** to refer to the UI field. Do not use **field** or **box**. For Don't use a descriptor with **button**. -- Do: Select **Run pipelines**. -- Do not: Select the **Run pipelines** button. +Use: + +- Select **Run pipelines**. + +Instead of: + +- Select the **Run pipelines** button. ## cannot, can not @@ -148,6 +171,13 @@ If you must refer to the checkbox, you can say it is selected or cleared. For ex - Ensure the **Protect environment** checkbox is cleared. - Ensure the **Protect environment** checkbox is selected. +## checkout, check out + +Use **check out** as a verb. For the Git command, use `checkout`. + +- Use `git checkout` to check out a branch locally. +- Check out the files you want to edit. + ## CI/CD CI/CD is always uppercase. No need to spell it out on first use. @@ -185,8 +215,8 @@ When writing about the Developer role: - Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer role. Instead, write it out. For example, **if you are assigned the Developer role**. - To describe a situation where the Developer role is the minimum required: - - Do: at least the Developer role - - Do not: the Developer role or higher + - Use: at least the Developer role + - Instead of: the Developer role or higher Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. @@ -208,8 +238,13 @@ For example: Use **earlier** when talking about version numbers. -- Do: In GitLab 14.1 and earlier. -- Do not: In GitLab 14.1 and lower. +Use: + +- In GitLab 14.1 and earlier. + +Instead of: + +- In GitLab 14.1 and lower. ## easily @@ -245,8 +280,13 @@ Use lowercase for **epic board**. Try to avoid **etc.**. Be as specific as you can. Do not use [**and so on**](#and-so-on) as a replacement. -- Do: You can update objects, like merge requests and issues. -- Do not: You can update objects, like merge requests, issues, etc. +Use: + +- You can update objects, like merge requests and issues. + +Instead of: + +- You can update objects, like merge requests, issues, etc. ## expand @@ -256,8 +296,13 @@ Use **expand** instead of **open** when you are talking about expanding or colla Use **box** instead of **field** or **text box**. -- Do: In the **Variable name** box, enter `my text`. -- Do not: In the **Variable name** field, enter `my text`. +Use: + +- In the **Variable name** box, enter `my text`. + +Instead of: + +- In the **Variable name** field, enter `my text`. However, you can make an exception when you are writing a task and you need to refer to all of the fields at once. For example: @@ -311,8 +356,8 @@ When writing about the Guest role: - Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest role. Instead, write it out. For example, **if you are assigned the Guest role**. - To describe a situation where the Guest role is the minimum required: - - Do: at least the Guest role - - Do not: the Guest role or higher + - Use: at least the Guest role + - Instead of: the Guest role or higher Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. @@ -328,16 +373,26 @@ Do not use **high availability** or **HA**. Instead, direct readers to the GitLa Do not use **higher** when talking about version numbers. -- Do: In GitLab 14.4 and later... -- Do not: In GitLab 14.4 and higher... -- Do not: In GitLab 14.4 and above... +Use: + +- In GitLab 14.4 and later... + +Instead of: + +- In GitLab 14.4 and higher... +- In GitLab 14.4 and above... ## hit Don't use **hit** to mean **press**. -- Do: Press **ENTER**. -- Do not: Hit the **ENTER** button. +Use: + +- Press **ENTER**. + +Instead of: + +- Hit the **ENTER** button. ## I @@ -369,13 +424,31 @@ Do not use **build** to be synonymous with **job**. A job is defined in the `.gi If you want to use **CI** with the word **job**, use **CI/CD job** rather than **CI job**. +## Kubernetes executor + +GitLab Runner can run jobs on a Kubernetes cluster. To do this, GitLab Runner uses the Kubernetes executor. + +When referring to this feature, use: + +- Kubernetes executor for GitLab Runner +- Kubernetes executor + +Do not use: + +- GitLab Runner Kubernetes executor, because this can infringe on the Kubernetes trademark. + ## later Use **later** when talking about version numbers. -- Do: In GitLab 14.1 and later... -- Do not: In GitLab 14.1 and higher... -- Do not: In GitLab 14.1 and above... +Use: + +- In GitLab 14.1 and later... + +Instead of: + +- In GitLab 14.1 and higher... +- In GitLab 14.1 and above... ## list @@ -390,8 +463,13 @@ Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the use Do not use **lower** when talking about version numbers. -- Do: In GitLab 14.1 and earlier. -- Do not: In GitLab 14.1 and lower. +Use: + +- In GitLab 14.1 and earlier. + +Instead of: + +- In GitLab 14.1 and lower. ## Maintainer @@ -402,8 +480,8 @@ When writing about the Maintainer role: - Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer role. Instead, write it out. For example, **if you are assigned the Maintainer role**. - To describe a situation where the Maintainer role is the minimum required: - - Do: at least the Maintainer role - - Do not: the Maintainer role or higher + - Use: at least the Maintainer role + - Instead of: the Maintainer role or higher Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. @@ -446,8 +524,14 @@ Do not use **navigate**. Use **go** instead. For example: Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. -- Do: You must set the variable. Or: Set the variable. -- Do not: You need to set the variable. +Use: + +- You must set the variable. +- Set the variable. + +Instead of: + +- You need to set the variable. **Should** is acceptable for recommended actions or items, or in cases where an event may not happen. For example: @@ -461,22 +545,63 @@ happen. For example: Do not use **note that** because it's wordy. -- Do: You can change the settings. -- Do not: Note that you can change the settings. +Use: + +- You can change the settings. + +Instead of: + +- Note that you can change the settings. ## on When documenting how to select high-level UI elements, use the word **on**. -- Do: `On the left sidebar...` +Use: + +- `On the left sidebar...` + +Instead of: + - Do not: `From the left sidebar...` or `In the left sidebar...` ## once The word **once** means **one time**. Don't use it to mean **after** or **when**. -- Do: When the process is complete... -- Do not: Once the process is complete... +Use: + +- When the process is complete... + +Instead of: + +- Once the process is complete... + +## only + +Put the word **only** next to the word it modifies. + +- You can create only private projects. + +In this example, **only** modifies the noun **projects**. The sentence means you can create one type of project--a private project. + +- You can only create private projects. + +In this example, **only** modifies the verb **create**. This sentence means that you can't perform other actions, +like deleting private projects, or adding users to them. + +## override + +Use **override** to indicate temporary replacement. + +For example, a value might be overridden when a job runs. The +original value does not change. + +## overwrite + +Use **overwrite** to indicate permanent replacement. + +For example, a log file might overwrite a log file of the same name. ## Owner @@ -518,8 +643,8 @@ When writing about the Reporter role: - Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter role. Instead, write it out. For example, **if you are assigned the Reporter role**. - To describe a situation where the Reporter role is the minimum required: - - Do: at least the Reporter role - - Do not: the Reporter role or higher + - Use: at least the Reporter role + - Instead of: the Reporter role or higher Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. @@ -541,8 +666,13 @@ Use lowercase for **runners**. These are the agents that run CI/CD jobs. See als Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: -- Do: Select the jobs you want. -- Do not: Select the job(s) you want. +Use: + +- Select the jobs you want. + +Instead of: + +- Select the job(s) you want. If you can select multiples of something, then write the word as plural. @@ -564,7 +694,12 @@ into separate areas, refer to these areas as sections. We often think of expandable/collapsible areas as **sections**. When you refer to expanding or collapsing a section, don't include the word **section**. -- Do: Expand **Auto DevOps**. +Use: + +- Expand **Auto DevOps**. + +Instead of: + - Do not: Expand the **Auto DevOps** section. ## select @@ -597,8 +732,13 @@ Do not use **simply** or **simple**. If the user doesn't find the process to be The word **since** indicates a timeframe. For example, **Since 1984, Bon Jovi has existed**. Don't use **since** to mean **because**. -- Do: Because you have the Developer role, you can delete the widget. -- Do not: Since you have the Developer role, you can delete the widget. +Use: + +- Because you have the Developer role, you can delete the widget. + +Instead of: + +- Since you have the Developer role, you can delete the widget. ## slashes @@ -616,8 +756,13 @@ Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#val Do not use **that** when describing a noun. For example: -- Do: The file you save... -- Do not: The file **that** you save... +Use: + +- The file you save... + +Instead of: + +- The file **that** you save... See also [this, these, that, those](#this-these-that-those). @@ -636,8 +781,13 @@ Use **text box** instead of **field** or **box** when referring to the UI elemen Try to avoid **there is** and **there are**. These phrases hide the subject. -- Do: The bucket has holes. -- Do not: There are holes in the bucket. +Use: + +- The bucket has holes. + +Instead of: + +- There are holes in the bucket. ## they @@ -649,17 +799,17 @@ a gender-neutral pronoun. Always follow these words with a noun. For example: -- Do: **This setting** improves performance. -- Do not: **This** improves performance. +- Use: **This setting** improves performance. +- Instead of: **This** improves performance. -- Do: **These pants** are the best. -- Do not: **These** are the best. +- Use: **These pants** are the best. +- Instead of: **These** are the best. -- Do: **That droid** is the one you are looking for. -- Do not: **That** is the one you are looking for. +- Use: **That droid** is the one you are looking for. +- Instead of: **That** is the one you are looking for. -- Do: **Those settings** need to be configured. (Or even better, **Configure those settings.**) -- Do not: **Those** need to be configured. +- Use: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Instead of: **Those** need to be configured. ## to-do item @@ -683,6 +833,19 @@ Do not use **type** if you can avoid it. Use **enter** instead. Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) +## user, users + +When possible, address the reader directly, instead of calling them **users**. +Use the [second person](#you-your-yours), **you**, instead. + +Use: + +- You can configure a pipeline. + +Instead of: + +- Users can configure a pipeline. + ## utilize Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. @@ -700,8 +863,13 @@ Do not use Latin abbreviations. Use **with**, **through**, or **by using** inste Try to avoid **we** and focus instead on how the user can accomplish something in GitLab. -- Do: Use widgets when you have work you want to organize. -- Do not: We created a feature for you to add widgets. +Use: + +- Use widgets when you have work you want to organize. + +Instead of: + +- We created a feature for you to add widgets. One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) @@ -709,5 +877,18 @@ One exception: You can use **we recommend** instead of **it is recommended** or Do not use **whitelist**. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +## you, your, yours + +Use **you**, **your**, and **yours** instead of [**the user** and **the user's**](#user-users). +Documentation should be from the [point of view](https://design.gitlab.com/content/voice-tone#point-of-view) of the reader. + +Use: + +- You can configure a pipeline. + +Instead of: + +- Users can configure a pipeline. + <!-- vale on --> <!-- markdownlint-enable --> diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 782cd3411b1..49ad51874e3 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -4,66 +4,44 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Documentation process +# How to update GitLab documentation -The process for creating and maintaining GitLab product documentation allows -anyone to contribute a merge request or create an issue for GitLab -documentation. - -Documentation updates relating to new features or feature enhancements must -use the [feature workflow process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) described in the GitLab Handbook. - -## Who updates the docs? - -*Anyone* can contribute! You can create a merge request for documentation when: +Anyone can contribute to the GitLab documentation! You can create a merge request for documentation when: - You find errors or other room for improvement in existing documentation. - You have an idea for all-new documentation that would help a GitLab user or administrator to accomplish their work with GitLab. -## Documentation labels - -Regardless of the type of issue or merge request, certain labels are required when documentation -is added or updated. The following are added by the issue or merge request author: - -- An appropriate [type label](../contributing/issue_workflow.md#type-labels). -- The [stage label](../contributing/issue_workflow.md#stage-labels) and - [group label](../contributing/issue_workflow.md#group-labels). For example, `~devops::create` and - `~group::source code`. -- The `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). - -The following are also added by members of the Technical Writing team: - -- A documentation [scoped label](../../user/project/labels.md#scoped-labels) with the - `docs::` prefix. For example, `~docs::improvement`. -- The `~Technical Writing` [team label](../contributing/issue_workflow.md#team-labels). - -Documentation changes that are not associated with the release of a new or updated feature -do not take the `~"type::feature"` label, but still need the `~documentation` label. - -They may include: - -- Documentation created or updated to improve accuracy, completeness, ease of use, or any reason - other than a [feature change](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change). -- Addressing gaps in existing documentation, or making improvements to existing documentation. -- Work on special projects related to the documentation. +If you are working on a feature or enhancement, use the +[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change). ## How to update the docs -To update GitLab documentation: - -1. Either: - - Click the **Edit this Page** link at the bottom of any page on <https://docs.gitlab.com>. - - Navigate to one of the repositories and documentation paths listed on the - [GitLab Documentation guidelines](index.md) page. -1. Follow the described standards and processes listed on the page, including: - - The [Structure and template](structure.md) page. - - The [Style Guide](styleguide/index.md). - - The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/). -1. Follow the [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). - -NOTE: -Work in a fork if you do not have the Developer role in the GitLab project. +If you are not a GitLab team member, or do not have the Developer role for the GitLab repository, to update GitLab documentation: + +1. Select an issue you'd like to work on. + - You don't need an issue to open a merge request. + - For a Hackathon, in the issue, in a comment, mention the person who opened the issue and ask for the issue to be assigned to you. + To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue. + If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale](testing.md#vale) issues. +1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). +1. In the top-right, select **Fork**. Forking makes a copy of the repository on GitLab.com. +1. In your fork, find the documentation page by going to the `\doc` directory. +1. If you know Git, make your changes and open a merge request. + If not, follow these steps: + 1. In the top right, select **Edit**, make the changes, and **Save**. + 1. From the left menu, select **Merge requests**. + 1. For the source branch, select your fork and branch. If you did not create a branch, select `master`. + For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch. + 1. For the commit message, use 3-5 words, start with a capital letter, and do not end with a period. + 1. Select **Commit changes**. A merge request opens. + 1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one. + +If you need help while working on the page, view: + +- The [Style Guide](styleguide/index.md). +- The [Word list](styleguide/word_list.md) +- The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/). ### Ask for help @@ -83,6 +61,22 @@ To identify someone who can help you: If you are a member of the GitLab Slack workspace, you can request help in `#docs`. +## Documentation labels + +When you author an issue or merge request, you must add these labels: + +- A [type label](../contributing/issue_workflow.md#type-labels). +- A [stage label](../contributing/issue_workflow.md#stage-labels) and [group label](../contributing/issue_workflow.md#group-labels). + For example, `~devops::create` and `~group::source code`. +- A `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). + +A member of the Technical Writing team adds these labels: + +- A [documentation scoped label](../../user/project/labels.md#scoped-labels) with the + `docs::` prefix. For example, `~docs::improvement`. +- The [`~Technical Writing` team label](../contributing/issue_workflow.md#team-labels). +- A type label: either `~"type::feature"` or `~"type::maintenance"`. + ### Reviewing and merging Anyone with the [Maintainer role](../../user/permissions.md) to the relevant GitLab project can @@ -130,9 +124,9 @@ immediately after merge by the developer or maintainer. For this, create an issue using the [Doc Review description template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review) and link to it from the merged merge request that introduced the documentation change. -Circumstances, where a regular pre-merge Technical Writer review might be skipped, include: +Circumstances in which a regular pre-merge Technical Writer review might be skipped include: -- There is a short amount of time left before the milestone release. If less than three +- There is a short amount of time left before the milestone release. If fewer than three days are remaining, seek a post-merge review and ping the writer via Slack to ensure the review is completed as soon as possible. - The size of the change is small and you have a high degree of confidence |
