diff options
Diffstat (limited to 'doc/development/documentation')
18 files changed, 680 insertions, 319 deletions
diff --git a/doc/development/documentation/alpha_beta.md b/doc/development/documentation/alpha_beta.md new file mode 100644 index 00000000000..d421aae3cb9 --- /dev/null +++ b/doc/development/documentation/alpha_beta.md @@ -0,0 +1,49 @@ +--- +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects +stage: none +group: unassigned +--- + +# Documenting Experiment and Beta features + +Some features are not generally available and are instead considered +[Experiment or Beta](../../policy/alpha-beta-support.md). + +When you document a feature in one of these three statuses: + +- Add `(Experiment)` or `(Beta)` in parentheses after the page or topic title. +- Do not include `(Experiment)` or `(Beta)` in the left nav. +- Ensure the version history lists the feature's status. + +These features are usually behind a feature flag, which follow [these documentation guidelines](feature_flags.md). + +If you add details of how users should enroll, or how to contact the team with issues, +the `FLAG:` note should be above these details. + +For example: + +```markdown +## Great new feature (Experiment) + +> [Introduced](link) in GitLab 15.10. This feature is an [Experiment](<link_to>/policy/alpha-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to enable the feature flag named `example_flag`. +On GitLab.com, this feature is not available. This feature is not ready for production use. + +Use this great new feature when you need to do this new thing. + +This feature is an [Experiment](<link_to>/policy/alpha-beta-support.md). To join +the list of users testing this feature, do this thing. If you find a bug, +[open an issue](link). +``` + +When the feature is ready for production, remove: + +- The text in parentheses. +- Any language about the feature not being ready for production in the body + description. +- The feature flag information if available. + +Ensure the version history is up-to-date by adding a note about the production release. diff --git a/doc/development/documentation/contribute.md b/doc/development/documentation/contribute.md new file mode 100644 index 00000000000..8b08743c6e9 --- /dev/null +++ b/doc/development/documentation/contribute.md @@ -0,0 +1,83 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Contribute to the GitLab documentation + +Everyone is welcome to update the GitLab documentation! + +## Work without an issue + +You don't need an issue to update the documentation. + +On [https://docs.gitlab.com](https://docs.gitlab.com), at the bottom of any page, +you can select **View page source** or **Edit in Web IDE** and [get started with a merge request](#open-your-merge-request). + +You can alternately: + +- Choose a page [in the `/doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) + and edit it from there. +- Try installing and running the [Vale linting tool](testing.md#vale) + and fixing the resulting issues. + +When you're developing code, the workflow for updating docs is slightly different. +For details, see the [merge request workflow](../contributing/merge_request_workflow.md). + +## Search available issues + +If you're looking for an open issue, you can +[review the list of documentation issues curated specifically for new contributors](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=documentation&label_name%5B%5D=docs-only&label_name%5B%5D=Seeking%20community%20contributions&first_page_size=20). + +When you find an issue you'd like to work on: + +- If the issue is already assigned to someone, pick a different one. +- If the issue is unassigned, add a comment and ask to work on the issue. For a Hackathon, use `@docs-hackathon`. Otherwise, use `@gl-docsteam`. For example: + + ```plaintext + @docs-hackathon I would like to work on this issue + ``` + +- Do not ask for more than three issues at a time. + +## Open your merge request + +When you are ready to update the documentation: + +1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). +1. In the upper-right corner, select **Fork**. Forking makes a copy of the repository on GitLab.com. +1. In your fork, find the documentation page in the `\doc` directory. +1. If you know Git, make your changes and open a merge request. + If not, follow these steps: + 1. In the upper-right corner, select **Edit** if it is visible. + If it is not, select the down arrow (**{chevron-lg-down}**) next to + **Open in Web IDE** or **Gitpod**, and select **Edit**. + 1. In the **Commit message** text box, enter a commit message. + Use 3-5 words, start with a capital letter, and do not end with a period. + 1. Select **Commit changes**. + 1. On the left sidebar, select **Merge requests**. + 1. Select **New merge request**. + 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. Select **Compare branches and continue**. A new 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. + 1. Select **Create merge request**. + +## Ask for help + +Ask for help from the Technical Writing team if you: + +- Need help to choose the correct place for documentation. +- Want to discuss a documentation idea or outline. +- Want to request any other help. + +To identify someone who can help you: + +1. Locate the Technical Writer for the relevant + [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). +1. Either: + - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. + - If non-urgent help is required, ping the Technical Writer in the issue or merge request. + +If you are a member of the GitLab Slack workspace, you can request help in the `#docs` channel. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 37be2178592..854faa839ef 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -7,33 +7,32 @@ description: "GitLab development - how to document features deployed behind feat # Document features deployed behind feature flags -GitLab uses [feature flags](../feature_flags/index.md) to strategically roll -out the deployment of its own features. The way we document a feature behind a -feature flag depends on its state (enabled or disabled). When the state -changes, the developer who made the change **must update the documentation** -accordingly. +GitLab uses [feature flags](../feature_flags/index.md) to roll +out the deployment of its own features. + +When the state of a feature flag changes, the developer who made the change +**must update the documentation**. ## When to document features behind a feature flag Every feature introduced to the codebase, even if it's behind a disabled feature flag, must be documented. For more information, see -[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). +[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Experiment or Beta](../../policy/alpha-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Experiment or Beta features](alpha_beta.md). + +When the feature is [implemented in multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), +discuss the plan with your technical writer. -When the feature is [implemented over multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), -discuss the exact documentation plan with your technical writer. Consider -creating a dedicated documentation issue if the feature: +You can create a documentation issue and delay the documentation if the feature: - Is far-reaching (makes changes across many areas of GitLab), like navigation changes. - Includes many MRs. - Affects more than a few documentation pages. - Is not fully functional if the feature flag is enabled for testing. -If you and the technical writer agree to delay the product documentation (for example, until after testing), -collaborate with the TW to create a documentation issue detailing the plan for adding the content. -The PM and EM should be included in the discussions to make sure the task of adding the documentation is assigned and scheduled. -Despite any planned delays, every feature flag in the codebase is automatically listed at -<https://docs.gitlab.com/ee/user/feature_flags.html#available-feature-flags>, -even when the feature is not fully functional. +The PM, EM, and writer should make sure the documentation work is assigned and scheduled. + +Every feature flag in the codebase is [in the documentation](../../user/feature_flags.md), +even when the feature is not fully functional or otherwise documented. ## How to add feature flag documentation @@ -57,13 +56,6 @@ Possible version history entries are: > - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed. ``` -You can combine entries if they happened in the same release: - -```markdown -> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. -``` - ## Use a note to describe the state of the feature flag Information about feature flags should be in a `FLAG` note at the start of the topic (just below the version history). @@ -144,3 +136,41 @@ And, when the feature is done and fully available to all users: > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. > - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. ``` + +## Simplify long version history + +The version history can get long, but you can sometimes simplify or remove entries. + +Combine entries if they happened in the same release: + +- Before: + + ```markdown + > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. + > - [Enabled on GitLab.com](issue-link) in GitLab 14.3. + > - [Enabled on self-managed](issue-link) in GitLab 14.3. + ``` + +- After: + + ```markdown + > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. + > - [Enabled on GitLab.com and self-managed](issue-link) in GitLab 14.3. + ``` + +Remove `Enabled on GitLab.com` entries when the feature is enabled by default for both GitLab.com and self-managed: + +- Before: + + ```markdown + > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. + > - [Enabled on GitLab.com](issue-link) in GitLab 15.9. + > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed. + ``` + +- After: + + ```markdown + > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. + > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed. + ``` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index fd9e885e097..6811b3d6584 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -107,8 +107,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- ``` -If you need help determining the correct stage, read [Ask for help](workflow.md#ask-for-help). - ### Redirection metadata The following metadata should be added when a page is moved to another location: @@ -116,21 +114,6 @@ The following metadata should be added when a page is moved to another location: - `redirect_to`: The relative path and filename (with an `.md` extension) of the location to which visitors should be redirected for a moved page. [Learn more](redirects.md). -- `disqus_identifier`: Identifier for Disqus commenting system. Used to keep - comments with a page that has been moved to a new URL. - [Learn more](redirects.md#redirections-for-pages-with-disqus-comments). - -### Comments metadata - -The [docs website](site_architecture/index.md) has comments (provided by Disqus) -enabled by default. In case you want to disable them (for example in index pages), -set it to `false`: - -```yaml ---- -comments: false ---- -``` ### Additional page metadata @@ -157,21 +140,31 @@ You can use a Rake task to update the `CODEOWNERS` file. #### Update the `CODEOWNERS` file -To update the `CODEOWNERS` file: +When groups or [TW assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) +change, you must update the `CODEOWNERS` file: -1. Review the [TW team assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) - in the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) - file. If any assignments have changed: - 1. Update the `codeowners.rake` file with the changes. - 1. Assign the merge request to a technical writing manager for review and merge. -1. After the changes to `codeowners.rake` are merged, go to the root of the `gitlab` repository. +1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR. +1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes. +1. Go to the root of the `gitlab` repository. 1. Run the Rake task with this command: `bundle exec rake tw:codeowners` -1. Review the command output for any pages that need attention to - their metadata. Handle any needed changes in a separate merge request. -1. Add the changes to the CODEOWNERS file to Git: `git add .gitlab/CODEOWNERS` -1. Commit your changes to your branch, and push your branch up to `origin`. +1. Review the changes in the `CODEOWNERS` file. +1. Add and commit all your changes and push your branch up to `origin`. 1. Create a merge request and assign it to a technical writing manager for review. +When updating the `codeowners.rake` file: + +- To specify multiple writers for a single group, use a space between writer names: + + ```plaintext + CodeOwnerRule.new('Group Name', '@writer1 @writer2'), + ``` + +- For a group that does not have an assigned writer, include the group name in the file and comment out the line: + + ```plaintext + # CodeOwnerRule.new('Group Name', ''), + ``` + ## Move, rename, or delete a page See [redirects](redirects.md). @@ -194,9 +187,8 @@ Further needs for what would make the doc even better should be immediately addr in a follow-up merge request or issue. If the release version you want to add the documentation to has already been -frozen or released, use the label `~"Pick into X.Y"` to get it merged into -the correct release. Avoid picking into a past release as much as you can, as -it increases the work of the release managers. +released, follow the [patch release runbook](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/patch/engineers.md) +to get it merged into the current version. ## GitLab `/help` @@ -359,28 +351,6 @@ feedback: false The default is to leave it there. If you want to omit it from a document, you must check with a technical writer before doing so. -## Disqus - -We have integrated the docs site with Disqus (introduced by -[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), -allowing our users to post comments. - -To omit only the comments from the feedback section, use the following key in -the front matter: - -```yaml ---- -comments: false ---- -``` - -We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), -since its content is too broad to comment on. Before omitting Disqus, you must -check with a technical writer. - -Note that after adding `feedback: false` to the front matter, it will omit -Disqus, therefore, don't add both keys to the same document. - The click events in the feedback section are tracked with Google Tag Manager. The conversions can be viewed on Google Analytics by navigating to **Behavior > Events > Top events > docs**. diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 4cfe8be713a..f080625ea9c 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -81,7 +81,6 @@ To redirect a page to another page in the same repository: - Replace both instances of `../newpath/to/file/index.md` with the new file path. - Replace both instances of `YYYY-MM-DD` with the expiration date, as explained in the template. -1. If the page has Disqus comments, follow [the steps for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). 1. If the page had images that aren't used on any other pages, delete them. After your changes are committed, search for and update all links that point to the old file: @@ -159,25 +158,13 @@ If you create a new page and then rename it before it's added to a release on th Instead of following that procedure, ask a Technical Writer to manually add the redirect to [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). -## Redirections for pages with Disqus comments +## Exceptions to creating a redirect -If the documentation page being relocated already has Disqus comments, -we need to preserve the Disqus thread. +In some cases you can skip adding the redirect and just delete the file. The page +must have already been removed from (or never existed in) the navigation, and one +of the following must be true: -Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier -is configured to be the page URL. Therefore, when we change the document location, -we need to preserve the old URL as the same Disqus identifier. - -To do that, add to the front matter the variable `disqus_identifier`, -using the old URL as value. For example, let's say we moved the document -available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, -`https://docs.gitlab.com/my-new-location/index.html`. - -Into the **new document** front matter, we add the following information. You must -include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. - -```yaml ---- -disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' ---- -``` +- The page was added and removed in the same release, so it was never included in + a self-managed release. +- The page does not contain any content of value, like a placeholder page or a page + with extremely low usage statistics. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index a92d58ead96..93afbf7e6dd 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -132,7 +132,7 @@ To deprecate an attribute: ``` To widely announce a deprecation, or if it's a breaking change, -[update the deprecations and removals documentation pages](../deprecation_guidelines/index.md#update-the-deprecations-and-removals-documentation-pages). +[update the REST API deprecations and removals page](../../api/rest/deprecations.md). ## Method description diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index ef6f3c0ae18..3e0534220a8 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -69,8 +69,7 @@ Sometimes pages for deprecated features are not in the global nav, depending on All other pages should be in the global nav. The technical writing team runs a report to determine which pages are not in the nav. -For now this report is manual, but [an issue exists](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1212) -to automate it. +The team reviews this list each month. ### Where to add diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index d4553614fad..849308f3086 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -33,7 +33,7 @@ Then you can use one of these approaches: of the documentation in the external repository. The landing page is indexed and searchable on <https://docs.gitlab.com>, but the rest of the documentation is not. For example, the [GitLab Workflow extension for VS Code](../../../user/project/repository/vscode.md). - We do not encourage the use of [pages with lists of links](../topic_types/index.md#topics-and-resources), + We do not encourage the use of [pages with lists of links](../topic_types/index.md#pages-and-topics-to-avoid), so only use this option if the recommended options are not feasible. ## Monthly release process (versions) diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 74437ea46c9..00307583be4 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -60,7 +60,7 @@ GitLab adds all troubleshooting information to the documentation, no matter how unlikely a user is to encounter a situation. GitLab Support maintains their own -[troubleshooting content](../../../administration/index.md#support-team-documentation) +[troubleshooting content](../../../administration/troubleshooting/index.md) in the GitLab documentation. ### The documentation includes all media types @@ -630,7 +630,7 @@ You can nest lists in other lists. ## Tables Tables should be used to describe complex information in a straightforward -manner. Note that in many cases, an unordered list is sufficient to describe a +manner. In many cases, an unordered list is sufficient to describe a list of items with a single, simple description per item. But, if you have data that's best described by a matrix, tables are the best choice. @@ -718,6 +718,15 @@ This is overridden by the [documentation-specific punctuation rules](#punctuatio Links help the docs adhere to the [single source of truth](#documentation-is-the-single-source-of-truth-ssot) principle. +However, you should avoid putting too many links on any page. Too many links can hinder readability. + +- Do not duplicate links on the same page. For example, on **Page A**, do not link to **Page B** multiple times. +- Avoid multiple links in a single paragraph. +- Avoid multiple links in a single task. +- On any one page, try not to use more than 15 links to other pages. +- Consider using [Related topics](../topic_types/index.md#related-topics) to reduce links that interrupt the flow of a task. +- Try to avoid anchor links to sections on the same page. Let users rely on the right navigation instead. + ### Links within the same repository To link to another page in the same repository, @@ -779,14 +788,18 @@ As much as possible, use text that follows one of these patterns: For example: -- `For more information, see [merge requests](../../../user/project/merge_requests/index.md).` -- `To create a review app, see [review apps](../../../ci/review_apps/index.md).` +- `For more information, see [merge requests](LINK).` +- `To create a review app, see [review apps](LINK).` You can expand on this text by using phrases like `For more information about this feature, see...` -Do not to use alternate phrases, like `Learn more about...` or -`To read more...`. +Do not to use the following constructions: + +- `Learn more about...` +- `To read more...`. +- `For more information, see the [Merge requests](LINK) page.` +- `For more information, see the [Merge requests](LINK) documentation.` #### Descriptive text rather than `here` @@ -1445,7 +1458,7 @@ For tab titles, be brief and consistent. Ensure they are parallel, and start eac For example: - `Linux package (Omnibus)`, `Helm chart (Kubernetes)` (when documenting configuration edits, follow the - [configuration edits guide](#configuration-documentation-for-different-installation-methods)) + [configuration edits guide](#how-to-document-different-installation-methods)) - `15.1 and earlier`, `15.2 and later` Until we implement automated testing for broken links to tabs ([Issue 1355](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1355)), do not link directly to a single tab, even though they do have unique URL parameters. @@ -1542,24 +1555,28 @@ If the document resides outside of the `doc/` directory, use the full path instead of the relative link: `https://docs.gitlab.com/ee/administration/restart_gitlab.html`. -### Installation guide +### How to document different installation methods -In [step 2 of the installation guide](../../../install/installation.md#2-ruby), -we install Ruby from source. To update the guide for a new Ruby version: +GitLab supports five official installation methods. If you're referring to +words as part of sentences and titles, use the following phrases: -- Change the version throughout the code block. -- Replace the sha256sum. It's available on the - [downloads page](https://www.ruby-lang.org/en/downloads/) of the Ruby website. - -### Configuration documentation for different installation methods +- Linux package +- Helm chart +- GitLab Operator +- Docker +- Self-compiled -GitLab supports four installation methods: +It's OK to add the explanatory parentheses when +[using tabs](#use-tabs-to-describe-a-self-managed-configuration-procedure): - Linux package (Omnibus) - Helm chart (Kubernetes) +- GitLab Operator (Kubernetes) - Docker - Self-compiled (source) +### Use tabs to describe a self-managed configuration procedure + Configuration procedures can require users to edit configuration files, reconfigure GitLab, or restart GitLab. In this case: @@ -1572,8 +1589,8 @@ GitLab, or restart GitLab. In this case: - The final step to reconfigure or restart GitLab can be used verbatim since it's the same every time. -You can copy and paste the following snippet when describing a configuration -edit: +When describing a configuration edit, you can use and edit to your liking the +following snippet: <!-- markdownlint-disable tabs-blank-lines --> ````markdown diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index e64fd4df7ff..094de2bd724 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -57,6 +57,7 @@ Instead of: - In GitLab 14.4 and above... - In GitLab 14.4 and higher... +- In GitLab 14.4 and newer... ## access level @@ -82,6 +83,11 @@ If you can add the phrase "by zombies" to the phrase, the construction is passive. For example, `The button is selected by zombies` is passive. `Zombies select the button` is active. +## Admin Area + +Use title case for **Admin Area** to refer to the area of the UI that you access when you select **Main menu > Admin**. +This area of the UI says **Admin Area** at the top of the page and on the menu. + ## administrator Use **administrator access** instead of **admin** when talking about a user's access level. @@ -99,10 +105,9 @@ Instead of: - To do this thing, you must have the Admin role. -## Admin Area +## advanced search -Use title case **Admin Area** to refer to the area of the UI that you access when you select **Main menu > Admin**. -This area of the UI says **Admin Area** at the top of the page and on the menu. +Use lowercase for **advanced search** to refer to the faster, more efficient search across the entire GitLab instance. ## agent @@ -113,7 +118,7 @@ For example: - Install the agent in your cluster. - Select an agent from the list. -Do not use title case **GitLab Agent** or **GitLab Agent for Kubernetes**. +Do not use title case for **GitLab Agent** or **GitLab Agent for Kubernetes**. ## agent access token @@ -145,13 +150,6 @@ Instead of: 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://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). -## Alpha - -Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** - -You might also want to link to [this section](../../../policy/alpha-beta-support.md#alpha-features) -in the handbook when writing about Alpha features. - ## analytics Use lowercase for **analytics** and its variations, like **contribution analytics** and **issue analytics**. @@ -210,7 +208,7 @@ Try to avoid **below** when referring to an example or table in a documentation Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** -You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta-features) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta) in the handbook when writing about Beta features. ## blacklist @@ -282,8 +280,7 @@ CI/CD is always uppercase. No need to spell it out on first use. ## CI/CD minutes -Use **CI/CD minutes** instead of **CI minutes**, **pipeline minutes**, **pipeline minutes quota**, or -**CI pipeline minutes**. This decision was made in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342813). +Do not use **CI/CD minutes**. This term was renamed to [**units of compute**](#units-of-compute). ## click @@ -293,7 +290,7 @@ Do not use **click**. Instead, use **select** with buttons, links, menu items, a ## cloud native When you're talking about using a Kubernetes cluster to host GitLab, you're talking about a **cloud-native version of GitLab**. -This version is different than the larger, more monolithic **Omnibus package** that is used to deploy GitLab. +This version is different than the larger, more monolithic **Linux package** that is used to deploy GitLab. You can also use **cloud-native GitLab** for short. It should be hyphenated and lowercase. @@ -301,6 +298,12 @@ You can also use **cloud-native GitLab** for short. It should be hyphenated and Use **collapse** instead of **close** when you are talking about expanding or collapsing a section in the UI. +## command line + +Use **From the command line** to introduce commands. + +Hyphenate when using as an adjective. For example, **a command-line tool**. + ## confirmation dialog Use **confirmation dialog** to describe the dialog box that asks you to confirm your action. For example: @@ -408,6 +411,7 @@ Use: Instead of: - In GitLab 14.1 and lower. +- In GitLab 14.1 and older. ## easily @@ -476,6 +480,13 @@ Instead of: Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. +## Experiment + +Use uppercase for **Experiment**. For example: **The XYZ feature is an Experiment.** or **This Experiment is ready to test.** + +You might also want to link to [this section](../../../policy/alpha-beta-support.md#experiment) +in the handbook when writing about Experiment features. + ## FAQ We want users to find information quickly, and they rarely search for the term **FAQ**. @@ -514,6 +525,17 @@ Filtering is different from [searching](#search). Do not use **foo** in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. +## fork + +A **fork** is a project that was created from a **upstream project** by using the +[forking process](../../../topics/git/terminology.md#fork). + +The **upstream project** (also known as the **source project**) and the **fork** have a **fork relationship** and are +**linked**. + +If the [**fork relationship** is removed](../../../user/project/repository/forking_workflow.md#unlink-a-fork), the +**fork** is **unlinked** from the **upstream project**. + ## future tense When possible, use present tense instead of future tense. For example, use **after you execute this command, GitLab displays the result** instead of **after you execute this command, GitLab will display the result**. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) @@ -530,9 +552,12 @@ Use title case for **Geo**. Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/brand/brand-activation/trademark-guidelines/). -## GitLab.com +## GitLab Flavored Markdown -**GitLab.com** refers to the GitLab instance managed by GitLab itself. +When possible, spell out [**GitLab Flavored Markdown**](../../../user/markdown.md). +([Vale](../testing.md#vale) rule: [`GLFM.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) + +If you must abbreviate, do not use **GFM**. Use **GLFM** instead. ## GitLab Helm chart, GitLab chart @@ -545,26 +570,41 @@ Do not use **the `gitlab` chart**, **the GitLab Chart**, or **the cloud-native c You use the **GitLab Helm chart** to deploy **cloud-native GitLab** in a Kubernetes cluster. -## GitLab Flavored Markdown +If you use it in a context of describing the +[different installation methods](index.md#how-to-document-different-installation-methods). +use `Helm chart (Kubernetes)`. -When possible, spell out [**GitLab Flavored Markdown**](../../../user/markdown.md). -([Vale](../testing.md#vale) rule: [`GLFM.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +## GitLab Pages -If you must abbreviate, do not use **GFM**. Use **GLFM** instead. +For consistency and branding, use **GitLab Pages** rather than **Pages**. + +However, if you use **GitLab Pages** for the first mention on a page or in the UI, +you can use **Pages** thereafter. + +## GitLab Runner + +Use title case for **GitLab Runner**. This is the product you install. For more information about the decision for this usage, +see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). + +See also: + +- [runners](#runner-runners) +- [runner managers](#runner-manager-runner-managers) +- [runner workers](#runner-worker-runner-workers) ## GitLab SaaS **GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the GitLab instance managed by GitLab itself. -## GitLab Runner - -Use title case for **GitLab Runner**. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). - ## GitLab self-managed Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. +## GitLab.com + +**GitLab.com** refers to the GitLab instance managed by GitLab itself. + ## guide We want to speak directly to users. On `docs.gitlab.com`, do not use **guide** as part of a page title. @@ -632,13 +672,29 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +## Installation from source + +When referring to the installation method using the self-compiled code, refer to it +as **self-compiled**. + +Use: + +- For self-compiled installations... + +Instead of: + +- For installations from source... + +For more information, see the +[different installation methods](index.md#how-to-document-different-installation-methods). + ## -ing words Remove **-ing** words whenever possible. They can be difficult to translate, and more precise terms are usually available. For example: - Instead of **The files using storage are deleted**, use **The files that use storage are deleted**. -- Instead of **Delete files using the Edit button**, use **Delete files by using the Edit button**. +- Instead of **Delete files using the Edit button**, use **Use the Edit button to delete files**. - Instead of **Replicating your server is required**, use **You must replicate your server**. ## issue @@ -699,6 +755,7 @@ Instead of: - In GitLab 14.1 and higher... - In GitLab 14.1 and above... +- In GitLab 14.1 and newer... ## list @@ -730,7 +787,7 @@ Do not use **limitations**. Use **known issues** instead. ## log in, log on -Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. +Do not use **log in** or **log on**. Use [sign in](#sign-in-sign-in) instead. If the user interface has **Log in**, you can use it. ## logged-in user, logged in user @@ -747,6 +804,7 @@ Use: Instead of: - In GitLab 14.1 and lower. +- In GitLab 14.1 and older. ## Maintainer @@ -803,6 +861,23 @@ Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it Use lowercase for **milestones**. +## Minimal Access + +When writing about the Minimal Access role: + +- Use a capital **M** and a capital **A**. +- Write it out: + - Use: if you are assigned the Minimal Access role + - Instead of: if you are a Minimal Access user + +- When the Minimal Access role is the minimum required role: + - Use: at least the Minimal Access role + - Instead of: the Minimal Access role or higher + +Do not use bold. + +Do not use **Minimal Access permissions**. A user who is assigned the Minimal Access role has a set of associated permissions. + ## n/a, N/A, not applicable When possible, use **not applicable**. Spelling out the phrase helps non-English speaking users and avoids @@ -835,6 +910,20 @@ When the variable is **optional**: - You can set the variable. +## newer + +Do not use **newer** when talking about version numbers. + +Use: + +- In GitLab 14.4 and later... + +Instead of: + +- In GitLab 14.4 and higher... +- In GitLab 14.4 and above... +- In GitLab 14.4 and newer... + ## normal, normally Don't use **normal** to mean the usual, typical, or standard way of doing something. @@ -865,6 +954,35 @@ Instead of: - Note that you can change the settings. +## older + +Do not use **older** when talking about version numbers. + +Use: + +- In GitLab 14.1 and earlier. + +Instead of: + +- In GitLab 14.1 and lower. +- In GitLab 14.1 and older. + +## Omnibus GitLab + +When referring to the installation method that uses the Linux package, refer to it +as **Linux package**. + +Use: + +- For installations that use the Linux package... + +Instead of: + +- For installations that use Omnibus GitLab... + +For more information, see the +[different installation methods](index.md#how-to-document-different-installation-methods). + ## on When documenting how to select high-level UI elements, use the word **on**. @@ -933,6 +1051,17 @@ An Owner is the highest role a user can have. Use title case for the GitLab Package Registry. +## page + +If you write a phrase like, "On the **Issues** page," ensure steps for how to get to the page are nearby. Otherwise, people might not know what the **Issues** page is. + +The page name should be visible in the UI at the top of the page. +If it is not, you should be able to get the name from the breadcrumb. + +The docs should match the case in the UI, and the page name should be bold. For example: + +- On the **Test cases** page, ... + ## permissions Do not use [**roles**](#roles) and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. @@ -947,6 +1076,17 @@ Use lowercase for **personal access token**. Do not use **please**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +## Premium + +Use **Premium**, in uppercase, for the subscription tier. When you refer to **Premium** +in the context of other subscription tiers, follow [the subscription tier](#subscription-tier) guidance. + +## prerequisites + +Use **prerequisites** when documenting the steps before a task. Do not use **requirements**. + +For more information, see [the task topic type](../topic_types/task.md). + ## press Use **press** when talking about keyboard keys. For example: @@ -1009,6 +1149,12 @@ Do not use **Reporter permissions**. A user who is assigned the Reporter role ha Use title case for **Repository Mirroring**. +## requirements + +Use **prerequisites** when documenting the steps before a task. Do not use **requirements**. + +For more information, see [the task topic type](../topic_types/task.md). + ## respectively Avoid **respectively** and be more precise instead. @@ -1045,6 +1191,14 @@ Use lowercase for **runners**. These are the agents that run CI/CD jobs. See als When referring to runners, if you have to specify that the runners are installed on a customer's GitLab instance, use **self-managed** rather than **self-hosted**. +## runner manager, runner managers + +Use lowercase for **runner managers**. These are a type of runner that can create multiple runners for autoscaling. See also [GitLab Runner](#gitlab-runner). + +## runner worker, runner workers + +Use lowercase for **runner workers**. This is the process created by the runner on the host computing platform to run jobs. See also [GitLab Runner](#gitlab-runner). + ## (s) Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: @@ -1120,14 +1274,17 @@ Use **setup** as a noun, and **set up** as a verb. For example: - Your remote office setup is amazing. - To set up your remote office correctly, consider the ergonomics of your work area. -## sign in +## sign in, sign-in -Use **sign in** or **sign in to**. +Use **sign in** or **sign in to** as a verb to describe the action of signing in. Do not use **sign on** or **sign into**, or **log on**, **log in**, or **log into**. If the user interface has different words, use those. +You can use **sign-in** as a noun or adjective. For example, **sign-in page** or +**sign-in restrictions**. + You can use **single sign-on**. ## sign up @@ -1202,6 +1359,13 @@ Use lowercase for **terminal**. For example: - Open a terminal. - From a terminal, run the `docker login` command. +## Terraform Module Registry + +Use title case for the GitLab Terraform Module Registry, but use lowercase `m` when +talking about non-specific modules. For example: + +- You can publish a Terraform module to your project's Terraform Module Registry. + ## text box Use **text box** instead of **field** or **box** when referring to the UI element. @@ -1277,6 +1441,24 @@ For example: See also [**enter**](#enter). +## Ultimate + +Use **Ultimate**, in uppercase, for the subscription tier. When you refer to **Ultimate** +in the context of other subscription tiers, follow [the subscription tier](#subscription-tier) guidance. + +## units of compute + +Use **units of compute** instead of these (or similar) terms: + +- **CI/CD minutes** +- **CI minutes** +- **pipeline minutes** +- **CI pipeline minutes** +- **pipeline minutes quota** + +This language is still being standardized in the documentation and UI beginning in March, 2023. +For more information, see [issue 5218](https://gitlab.com/gitlab-com/Product/-/issues/5218). + ## units of measurement Use a space between the number and the unit of measurement. For example, **128 GB**. @@ -1314,7 +1496,10 @@ See also [downgrade](#downgrade) and [roll back](#roll-back). ## upper left, upper right -Use **upper left** and **upper right** instead of **top left** and **top right**. Hyphenate as adjectives (for example, **upper-left corner**). +Use **upper-left corner** and **upper-right corner** to provide direction in the UI. +If the UI element is not in a corner, use **upper left** and **upper right**. + +Do not use **top left** and **top right**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right). diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 4f61b2424eb..4a7e206da20 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -49,17 +49,21 @@ To run tests locally, it's important to: ### Lint checks Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh) -script and can be executed as follows: +script and can be executed with the help of a Rake task as follows: -1. Go to the `gitlab` directory. +1. Go to your `gitlab` directory. 1. Run: ```shell - MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + rake lint:markdown ``` -Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. -If you omit it completely, it defaults to the `doc/` directory. +To specify a single file or directory you would like to run lint checks for, run: + +```shell +MD_DOC_PATH=path/to/my_doc.md rake lint:markdown +``` + The output should be similar to: ```plaintext @@ -77,7 +81,7 @@ The output should be similar to: This requires you to either: - Have the [required lint tools installed](#local-linters) on your computer. -- A working Docker installation, in which case an image with these tools pre-installed is used. +- A working Docker or containerd installation, to use an image with these tools pre-installed. ### Documentation link tests diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index 66af8780b9b..c9aedf940a2 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -37,9 +37,19 @@ Do not include links to related tasks. The navigation provides links to tasks. ## Concept topic titles -For the title text, use a noun. For example, `Widgets` or `GDK dependency management`. +For the title text, use a noun. For example: -If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`. +- `Widgets` +- `GDK dependency management` + +If you need more descriptive words, use the `ion` version of the word, rather than `ing`. For example: + +- `Object migration` instead of `Migrating objects` or `Migrate objects` + +Words that end in `ing` are hard to translate and take up more space, and active verbs are used for task topics. +For details, see [the Google style guide](https://developers.google.com/style/headings#heading-and-title-text). + +### Titles to avoid Avoid these topic titles: diff --git a/doc/development/documentation/topic_types/glossary.md b/doc/development/documentation/topic_types/glossary.md new file mode 100644 index 00000000000..4985101a391 --- /dev/null +++ b/doc/development/documentation/topic_types/glossary.md @@ -0,0 +1,70 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Glossary topic type + +A glossary provides a list of unfamiliar terms and their definitions to help users understand a specific +GitLab feature. + +Each glossary item provides a single term and its associated definition. The definition should answer the questions: + +- **What** is this? +- **Why** would you use it? + +For glossary terms: + +- Do not use jargon. +- Do not use internal terminology or acronyms. +- Ensure the correct usage is defined in the [word list](../styleguide/word_list.md). + +## Alternatives to glossaries + +Glossaries should provide short, concise term-definition pairs. + +- If a definition requires more than a brief explanation, use a concept topic instead. +- If you find yourself explaining how to use the feature, use a task topic instead. + +## Glossary example + +Glossary topics should be in this format. Use an unordered list primarily. You can use a table if you need to apply +additional categorization. + +Try to include glossary topics on pages that explain the feature, rather than as a standalone page. + +```markdown +## FeatureName glossary + +This glossary provides definitions for terms related to FeatureName. + +- **Term A**: Term A does this thing. +- **Term B**: Term B does this thing. +- **Term C**: Term C does this thing. +``` + +If you use the table format: + +```markdown +## FeatureName glossary + +This glossary provides definitions for terms related to FeatureName. + +| Term | Definition | Additional category | +|--------|-------------------------|---------------------| +| Term A | Term A does this thing. | | +| Term B | Term B does this thing. | | +| Term C | Term C does this thing. | | +``` + +## Glossary topic titles + +Use `FeatureName glossary`. + +Don't use alternatives to `glossary`. For example: + +- `Terminology` +- `Glossary of terms` +- `Glossary of common terms` +- `Definitions` diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index cfc231c268a..37ed876fc59 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -16,22 +16,52 @@ Each topic on a page should be one of the following topic types: Even if a page is short, the page usually starts with a concept and then includes a task or reference topic. -The tech writing team sometimes uses the acronym `CTRT` to refer to our topic types. +The tech writing team sometimes uses the acronym `CTRT` to refer to the topic types. The acronym refers to the first letter of each topic type. -In addition to the four primary topic types, we also have a page type for -[Tutorials](tutorial.md) and [Get started](#get-started). +## Other page and topic types + +In addition to the four primary topic types, you can use the following: + +- Page types: [Tutorials](tutorial.md) and [Get started](#get-started) +- Topic type: [Related topics](#related-topics) +- Page or topic type: [Glossaries](glossary.md) + +## Pages and topics to avoid + +You should avoid: + +- Pages that are exclusively links to other pages. The only exception are + top-level pages that aid with navigation. +- Topics that have one or two sentences only. In these cases: + - Incorporate the information in another topic. + - If the sentence links to another page, use a [Related topics](#related-topics) link instead. + +## Topic title guidelines + +In general, for topic titles: + +- Be clear and direct. Make every word count. +- Use articles and prepositions. +- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. +- Do not repeat text from earlier topic titles. For example, if the page is about merge requests, + instead of `Troubleshooting merge requests`, use only `Troubleshooting`. + +See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). ## Related topics If inline links are not sufficient, you can create a topic called **Related topics** and include an unordered list of related topics. This topic should be above the Troubleshooting section. +Links in this section should be brief and scannable. They are usually not +full sentences, and so should not end in a period. + ```markdown ## Related topics -- [Configure your pipeline](link-to-topic). -- [Trigger a pipeline manually](link-to-topic). +- [CI/CD variables](link-to-topic) +- [Environment variables](link-to-topic) ``` ## Get started @@ -57,22 +87,3 @@ consider using subsections for each distinct task. In the left nav, use `Get started` as the text. On the page itself, spell out the full name. For example, `Get started with application security`. - -## Topics and resources - -Some pages are solely a list of links to other documentation. - -We do not encourage this page type. Lists of links can get out-of-date quickly -and offer little value to users, who prefer to search to find information. - -## Topic title guidelines - -In general, for topic titles: - -- Be clear and direct. Make every word count. -- Use articles and prepositions. -- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. -- Do not repeat text from earlier topic titles. For example, if the page is about merge requests, - instead of `Troubleshooting merge requests`, use only `Troubleshooting`. - -See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 8d23a5f322e..2ddfd841ec3 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -60,6 +60,22 @@ For example, `Create an issue`. If several tasks on a page share prerequisites, you can create a separate topic with the title `Prerequisites`. +## When a task has only one step + +If you need to write a task that has only one step, make that step an unordered list item. +This format helps the step stand out, while keeping it consistent with the rules +for lists. + +For example: + +```markdown +# Create a merge request + +To create a merge request: + +- In the upper-right corner, select **New merge request**. +``` + ### When more than one way exists to perform a task If more than one way exists to perform a task in the UI, you should @@ -139,4 +155,4 @@ how to write the phrase for each role. ## Related topics -- [View the format for writing task steps](../styleguide/index.md#navigation). +- [How to write task steps](../styleguide/index.md#navigation) diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md index 1b1426a0465..2d57029b786 100644 --- a/doc/development/documentation/topic_types/tutorial.md +++ b/doc/development/documentation/topic_types/tutorial.md @@ -13,9 +13,28 @@ In general, you might consider using a tutorial when: of sub-steps. - The steps cover a variety of GitLab features or third-party tools. -Tutorials are learning aids that complement our core documentation. -They do not introduce new features. -Always use the primary [topic types](index.md) to document new features. +## Tutorial guidance + +- Tutorials are not [tasks](task.md). A task gives instructions for one procedure. + A tutorial combines multiple tasks to achieve a specific goal. +- Tutorials provide a working example. Ideally the reader can create the example the + tutorial describes. If they can't replicate it exactly, they should be able + to replicate something similar. +- Tutorials do not introduce new features. +- Tutorials do not need to adhere to the Single Source of Truth tenet. While it's not + ideal to duplicate content that is available elsewhere, it's worse to force the reader to + leave the page to find what they need. + +## Tutorial file name and location + +For tutorial Markdown files, you can either: + +- Save the file in a directory with the product documentation. +- Create a subfolder under `doc/tutorials` and name the file `index.md`. + +In the left nav, add the tutorial near the relevant feature documentation. + +Add a link to the tutorial on one of the [tutorial pages](../../../tutorials/index.md). ## Tutorial format @@ -31,7 +50,9 @@ To create a website: 1. [Do the first task](#do-the-first-task) 1. [Do the second task](#do-the-second-task) -Prerequisites (optional): +## Prerequisites + +This topic is optional. - Thing 1 - Thing 2 @@ -57,7 +78,7 @@ To do step 2: ``` An example of a tutorial that follows this format is -[Tutorial: Make your first Git commit](../../../tutorials/make_your_first_git_commit.md). +[Tutorial: Make your first Git commit](../../../tutorials/make_first_git_commit/index.md). ## Tutorial page title diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 30a0d4d4cf4..859e7265a2a 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -13,7 +13,7 @@ including when features were introduced and when they were updated or removed. ## View older documentation versions Previous versions of the documentation are available on `docs.gitlab.com`. -To view a previous version, select the **Versions** button in the upper right. +To view a previous version, in the upper-right corner, select **Versions**. To view versions that are not available on `docs.gitlab.com`: @@ -89,8 +89,9 @@ voters to agree. When features are deprecated and removed, update the related documentation. -API documentation follows these guidelines, but the GraphQL docs use -a [separate process](../api_graphql_styleguide.md#deprecating-schema-items). +NOTE: +A separate process exists for [GraphQL docs](../api_graphql_styleguide.md#deprecating-schema-items) +and [REST API docs](restful_api_styleguide.md#deprecations). ### Deprecate a page or topic diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index fe5453a4a58..1a4194aebd9 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -4,148 +4,39 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# How to update GitLab documentation +# Documentation workflow -Anyone can contribute to the GitLab documentation! You can create a merge request for documentation when: +Documentation at GitLab follows a workflow. -- 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. +## Before merging -If you are working on a feature or enhancement, use the -[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#documentation-for-a-product-change). +Ensure your documentation includes: -## Do not use ChatGPT or AI-generated content for the docs - -GitLab documentation is distributed under the [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/), which presupposes that GitLab owns the documentation. - -Under current law in the US and the EU, it’s possible that AI-generated works might either: - -- not be owned by anyone because they weren't created by a human, or -- belong to the AI training data’s creator, if the AI verbatim reproduces content that it trained on - -If the documentation contains AI-generated content, GitLab probably wouldn't own this content, which would risk invalidating the CC BY-SA 4.0 license. +- [Product badges](styleguide/index.md#product-tier-badges). +- The GitLab [version](versions.md) that introduced the feature. +- Accurate [links](styleguide/index.md#links). +- Accurate [user permissions](../../user/permissions.md). -Contributions to GitLab documentation are made under either our [DCO or our CLA terms](https://about.gitlab.com/community/contribute/dco-cla/). In both, contributors have to make certain certifications about the authorship of their work that they can't validly make for AI-generated text. - -For these reasons, do not add AI-generated content to the documentation. - -## How to update the docs - -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](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities) you'd like to work on. - - For a Hackathon, mention `@docs-hackathon` in a comment 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're not taking part in a Hackathon, you don't need an issue to open a merge request. - 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 upper right, select **Fork**. Forking makes a copy of the repository on GitLab.com. -1. In your fork, find the documentation page in the `\doc` directory. -1. If you know Git, make your changes and open a merge request. - If not, follow these steps: - 1. In the upper right, select **Edit** if it is visible. If it is not, select the down arrow (**{chevron-lg-down}**) next to **Open in Web IDE** or **Gitpod**, and select **Edit**. - 1. In the **Commit message** text box, enter a commit message. Use 3-5 words, start with a capital letter, and do not end with a period. - 1. Select **Commit changes**. - 1. On the left sidebar, select **Merge requests**. - 1. Select **New merge request**. - 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. Select **Compare branches and continue**. A new 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. - 1. Select **Create merge request**. - -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 - -Ask for help from the Technical Writing team if you: - -- Need help to choose the correct place for documentation. -- Want to discuss a documentation idea or outline. -- Want to request any other help. - -To identify someone who can help you: - -1. Locate the Technical Writer for the relevant - [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). -1. Either: - - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - - If non-urgent help is required, ping the Technical Writer in the issue or merge request. - -If you are a member of the GitLab Slack workspace, you can request help in `#docs`. +Ensure you've followed the [style guide](styleguide/index.md) and [word list](styleguide/word_list.md). ## Documentation labels -When you author an issue or merge request, you must add these labels: +When you author an issue or merge request, choose the +[Documentation template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md). +It includes these labels, which are added to the merge request: -- A [type label](../contributing/issue_workflow.md#type-labels), either `~"type::feature"` or `~"type::maintenance"`. -- A [stage label](../contributing/issue_workflow.md#stage-labels) and [group label](../contributing/issue_workflow.md#group-labels). +- A [type label](../labels/index.md#type-labels), either `~"type::feature"` or `~"type::maintenance"`. +- A [stage label](../labels/index.md#stage-labels) and [group label](../labels/index.md#group-labels). For example, `~devops::create` and `~group::source code`. -- A `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). +- A `~documentation` [specialization label](../labels/index.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). - -## Reviewing and merging - -Anyone with the Maintainer role to the relevant GitLab project can -merge documentation changes. Maintainers must make a good-faith effort to ensure that the content: - -- Is clear and sufficiently easy for the intended audience to navigate and understand. -- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). +- The [`~Technical Writing` team label](../labels/index.md#team-labels). -If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant -[DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). - -The process involves the following: - -- Primary Reviewer. Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) - or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped - for minor fixes without substantive content changes. -- Technical Writer (Optional). If not completed for a merge request before merging, must be scheduled - post-merge. Schedule post-merge reviews only if an urgent merge is required. To request a: - - Pre-merge review, assign the Technical Writer listed for the applicable - [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). - - Post-merge review, see [Post-merge reviews](#post-merge-reviews). -- Maintainer. For merge requests, Maintainers: - - Can always request any of the above reviews. - - Review before or after a Technical Writer review. - - Ensure the given release milestone is set. - - Ensure the appropriate labels are applied, including any required to pick a merge request into - a release. - - Ensure that, if there has not been a Technical Writer review completed or scheduled, they - [create the required issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review), assign it to the Technical Writer of the given stage group, - and link it from the merge request. - -The process is reflected in the **Documentation** -[merge request template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md). - -### Before merging - -Ensure the following if skipping an initial Technical Writer review: - -- [Product badges](styleguide/index.md#product-tier-badges) are applied. -- The GitLab [version](versions.md) that - introduced the feature is included. -- Changes to topic titles don't affect in-app hyperlinks. -- Specific [user permissions](../../user/permissions.md) are documented. -- New documents are linked from higher-level indexes, for discoverability. -- The style guide is followed: - - For [directories and files](site_architecture/folder_structure.md). - - For [images](styleguide/index.md#images). - -Merge requests that change the location of documentation must always be reviewed by a Technical -Writer before merging. - -### Post-merge reviews +## Post-merge reviews If not assigned to a Technical Writer for review prior to merging, a review must be scheduled immediately after merge by the developer or maintainer. For this, @@ -174,8 +65,25 @@ Remember: - The Technical Writer can also help decide that documentation can be merged without Technical writer review, with the review to occur soon after merge. -## Other ways to help +## Do not use ChatGPT or AI-generated content for the docs + +GitLab documentation is distributed under the [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/), which presupposes that GitLab owns the documentation. -If you have ideas for further documentation resources please -[create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation) -using the Documentation template. +Under current law in the US and the EU, it’s possible that AI-generated works might either: + +- not be owned by anyone because they weren't created by a human, or +- belong to the AI training data's creator, if the AI verbatim reproduces content that it trained on + +If the documentation contains AI-generated content, GitLab probably wouldn't own this content, which would risk invalidating the CC BY-SA 4.0 license. + +Contributions to GitLab documentation are made under either our [DCO or our CLA terms](https://about.gitlab.com/community/contribute/dco-cla/). In both, contributors have to make certain certifications about the authorship of their work that they can't validly make for AI-generated text. + +For these reasons, do not add AI-generated content to the documentation. + +## Related topics + +- [Reviews and levels of edit](https://about.gitlab.com/handbook/product/ux/technical-writing/#reviews) +- [Technical writing assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) +- The [Style Guide](styleguide/index.md) +- The [Word list](styleguide/word_list.md) +- The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) |