From cafa9ab0983e571c461989b731553a06a55d0aed Mon Sep 17 00:00:00 2001
From: Suzanne Selhorn <sselhorn@gitlab.com>
Date: Wed, 8 Mar 2023 19:16:49 +0000
Subject: [PATCH] Making contribute its own page
Related to: https://gitlab.com/gitlab-org/technical-writing/-/issues/744
---
doc/development/documentation/contribute.md | 54 +++++++
doc/development/documentation/index.md | 2 -
doc/development/documentation/workflow.md | 160 +++++---------------
3 files changed, 88 insertions(+), 128 deletions(-)
create mode 100644 doc/development/documentation/contribute.md
diff --git a/doc/development/documentation/contribute.md b/doc/development/documentation/contribute.md
new file mode 100644
index 000000000000..59621aaaad1e
--- /dev/null
+++ b/doc/development/documentation/contribute.md
@@ -0,0 +1,54 @@
+---
+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.
+
+If you are looking for something to work on, you can review the list of
+[open issues](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities)
+or work to fix [Vale](testing.md#vale) suggestions.
+
+You don't need an issue to update the documentation, however.
+
+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/index.md b/doc/development/documentation/index.md
index 207be5e2858d..d1f5ee8f9f32 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:
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 07ad07375e26..1a4194aebd9f 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -4,84 +4,26 @@ 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 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**.
-
-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](../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).
@@ -94,58 +36,7 @@ A member of the Technical Writing team adds these labels:
`docs::` prefix. For example, `~docs::improvement`.
- The [`~Technical Writing` team label](../labels/index.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).
-
-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/)
--
GitLab