<!-- Check the documentation structure guidelines for guidance: https://docs.gitlab.com/ee/development/documentation/structure.html-->
### Type of issue
- [ ] Documents Feature A <!-- feature name -->
- [ ] Follow-up from: #XXX, !YYY <!-- Mention related issues, MRs, and epics when available -->
<!-- Un-comment the line for the applicable doc issue type to add its label.
Note that all text on that line is deleted upon issue creation. -->
<!-- /label ~"docs:fix" - Correction or clarification needed. -->
<!-- /label ~"docs:new" - New doc needed to cover a new topic or use case. -->
<!-- /label ~"docs:improvement" - Improving an existing doc; e.g. adding a diagram, adding or rewording text, resolving redundancies, cross-linking, etc. -->
<!-- /label ~"docs:revamp" - Review a page or group of pages in order to plan and implement major improvements/rewrites. -->
<!-- /label ~"docs:other" - Anything else. -->
## New doc or update?
### Problem to solve
<!-- Mark either of these boxes: -->
<!-- Include the following detail as necessary:
* What product or feature(s) affected?
* What docs or doc section affected? Include links or paths.
* Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs?
* Any other ideas or requests?
-->
- [ ] New documentation
- [ ] Update existing documentation
### Further details
## Checklists
<!--
* Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab?
* Include use cases, benefits, and/or goals for this work.
* If adding content: What audience is it intended for? (What roles and scenarios?)
For ideas, see personas at https://design.gitlab.com/research/personas or the persona labels at
@@ -31,15 +31,20 @@ Existing personas are: (copy relevant personas out of this comment, and delete a
### Further details
<!--- Include use cases, benefits, and/or goals (contributes to our vision?) -->
<!-- Include use cases, benefits, and/or goals (contributes to our vision?) -->
### Proposal
<!--- How are we going to solve the problem? Try to include the user journey! -->
<!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey -->
### Documentation
<!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html
Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements -->
### What does success look like, and how can we measure that?
<!--- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this -->
<!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. -->
<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation -->
<!-- Follow the documentation workflow https://docs.gitlab.com/ee/development/documentation/workflow.html -->
<!-- Additional information is located at https://docs.gitlab.com/ee/development/documentation/ -->
<!-- Mention "documentation" or "docs" in the MR title -->
<!-- Use this description template for new docs or updates to existing docs. For changing documentation location use the "Change documentation location" template -->
<!-- For changing documentation location use the "Change documentation location" template -->
## What does this MR do?
<!-- Briefly describe what this MR is about -->
<!-- Briefly describe what this MR is about. -->
## Related issues
<!-- Mention the issue(s) this MR closes or is related to -->
Closes
<!-- Link related issues below. Insert the issue link or reference after the word "Closes" if merging this should automatically close it. -->
## Author's checklist
-[ ] [Apply the correct labels and milestone](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#1-product-managers-role)
- [ ] Crosslink the document from the higher-level index
- [ ] Crosslink the document from other subject-related docs
-[ ] Feature moving tiers? Make sure the change is also reflected in [`features.yml`](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml)
-[ ] Correctly apply the product [badges](https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges) and [tiers](https://docs.gitlab.com/ee/development/documentation/styleguide.html#gitlab-versions-and-tiers)
-[ ] [Port the MR to EE (or backport from CE)](https://docs.gitlab.com/ee/development/documentation/index.html#cherry-picking-from-ce-to-ee): _always recommended, required when the `ee-compat-check` job fails_
-[ ] Follow the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
- [ ] Link docs to and from the higher-level index page, plus other related docs where helpful.
- [ ] Apply the ~Documentation label.
## Review checklist
- [ ] Your team's review (required)
- [ ] PM's review (recommended, but not a blocker)
- [ ] Technical writer's review (required)
- [ ] Merge the EE-MR first, CE-MR afterwards
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
**1. Primary Reviewer**
* [ ] Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.
**2. Technical Writer**
*[ ] Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
**3. Maintainer**
1. [ ] Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
1. [ ] Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist.
1.[ ] If there has not been a technical writer review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review).
and [structure](https://docs.gitlab.com/ee/development/documentation/structure.html) guides.
Note that a technical writer will review all changes to documentation. This can occur
in the same MR as the feature code, but [if there is not sufficient time or need,
it can be planned via a follow-up issue for doc review](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#1-product-managers-role),
and another MR, if needed. Regardless, complete docs must be merged with code by the freeze.
#### What happens if these deadlines are missed?
...
...
@@ -206,8 +210,6 @@ and to prevent any last minute surprises.
Merge requests should still be complete, following the [definition of done][done].
#### Feature merge requests
If a merge request is not ready, but the developers and Product Manager
responsible for the feature think it is essential that it is in the release,
they can [ask for an exception](#asking-for-an-exception) in advance. This is
...
...
@@ -222,34 +224,17 @@ information, see
[Automatic CE->EE merge][automatic_ce_ee_merge] and
[Guidelines for implementing Enterprise Edition features][ee_features].
#### Documentation merge requests
Documentation is part of the product and must be shipped with the feature.
The single exception for the feature freeze is documentation, and it can
be left to be **merged up to the 14th** if:
* There is a follow-up issue to add documentation.
* It is assigned to the developer writing documentation for this feature, and they
are aware of it.
* It is in the correct milestone, with the labels ~Documentation, ~Deliverable,
~missed-deliverable, and "pick into X.Y" applied.
* It must be reviewed and approved by a technical writer.
Once the stable branch is frozen, the only MRs that can be cherry-picked into
the stable branch are:
* Fixes for [regressions](#regressions) where the affected version `xx.x` in `regression:xx.x` is the current release. See [Managing bugs](#managing-bugs) section.
* Fixes for security issues
* Fixes or improvements to automated QA scenarios
*[Documentation updates](https://docs.gitlab.com/ee/development/documentation/workflow.html#documentation-shipped-late) for changes in the same release
* New or updated translations (as long as they do not touch application code)
* Changes that are behind a feature flag and have the ~"feature flag" label
* Fixes for security issues.
* Fixes or improvements to automated QA scenarios.
*[Documentation improvements](https://docs.gitlab.com/ee/development/documentation/workflow.html) for feature changes made in the same release, though initial docs for these features should have already been merged by the freeze, as required.
* New or updated translations (as long as they do not touch application code).
* Changes that are behind a feature flag and have the ~"feature flag" label.
During the feature freeze all merge requests that are meant to go into the
upcoming release should have the correct milestone assigned _and_ the
{help: s_("Profiles|This email will be used for web based operations, such as edits and merges. %{learn_more}").html_safe%{learn_more: commit_email_docs_link}},
When your content is ready for review, assign the MR to a technical writer
according to the [DevOps stages](https://about.gitlab.com/handbook/product/categories/#devops-stages)
in the table below. If necessary, mention them in a comment explaining what needs
to be reviewed.
Per the [documentation workflows](https://docs.gitlab.com/ee/development/documentation/workflow.html), the review may occur prior to merging this MR **or** after a maintainer has agreed to review and merge this MR without a tech writer review. (Meanwhile, you are welcome to involve a technical writer at any time if you have questions about writing or updating the documentation. GitLabbers are also welcome to use the [#docs](https://gitlab.slack.com/archives/C16HYA2P5) channel on Slack.)
The technical writer who, by default, will review this content or collaborate as needed is dependent on the [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) to which the content applies:
You are welcome to mention them sooner if you have questions about writing or
updating the documentation. GitLabbers are also welcome to use the
[#docs](https://gitlab.slack.com/archives/C16HYA2P5) channel on Slack.
**To request a review prior to merging**
- Assign the MR to the applicable technical writer, above. If you are not sure which category the change falls within, or the change is not part of one of these categories, mention one of the usernames above.
**To request a review to commence after merging**
If you are not sure which category the change falls within, or the change is not
part of one of these categories, mention one of the usernames above.
- Create an issue for a doc review [using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and assign it to the applicable technicial writer from the table.
description:How to improve GitLab's documentation.
---
# Documentation improvement workflow
# Documentation Improvement Workflow
Anyone can contribute a merge request or create an issue for GitLab's documentation.
...
...
@@ -15,20 +15,24 @@ or feature enhancement, see the [feature-change documentation workflow](feature-
Anyone can contribute! You can create a merge request with documentation
when you find errors or other room for improvement in an existing doc, or when you
have an idea for all-new documentation that would help a GitLab user or admin
to achieve or improve their DevOps workflows.
have an idea for all-new documentation that would help a GitLab user or administrator
to accomplish their work with GitLab.
## How to update the docs
- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page,
including linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
- If you need any help to choose the correct place for a doc, discuss a documentation
1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to
one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page.
Work in a fork if you do not have developer access to the GitLab project.
1. Follow the described standards and processes listed on that Guidelines page,
including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace.
## Merging
## Review and merging
Anyone with master access to the affected GitLab project can merge documentation changes.
This person must make a good-faith effort to ensure that the content is clear
...
...
@@ -38,12 +42,22 @@ that it meets the [Documentation Guidelines](index.md) and [Style Guide](stylegu
If the author or reviewer has any questions, or would like a techncial writer's review
before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
## Technical Writer review
The process can involve the following parties/phases, and is replicated in the `Documentation` MR template for GitLab CE and EE, to help with following the process.
**1. 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.
**2. Technical Writer** - Optional - If not requested for this MR, must be scheduled post-merge. To request a pre-merge review, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
To request a post-merge review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
**3. Maintainer**
The technical writing team reviews changes after they are merged, unless a prior
review is requested.
1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review.
2. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
3. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
4. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
## Other ways to help
If you have ideas for further documentation resources that would be best
considered/handled by technical writers, devs, and other SMEs, please create an issue.
considered/handled by technical writers, devs, and other SMEs, please [create an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Documentation)
msgid "Labels|Promoting %{labelTitle} will make it available for all projects inside %{groupName}. Existing project labels with the same title will be merged. This action cannot be reversed."
msgstr ""
msgid "Language"
msgstr ""
msgid "Large File Storage"
msgstr ""
...
...
@@ -7220,6 +7223,9 @@ msgstr ""
msgid "Preferences|Navigation theme"
msgstr ""
msgid "Preferences|This feature is experimental and translations are not complete yet"
msgstr ""
msgid "Press Enter or click to search"
msgstr ""
...
...
@@ -7418,9 +7424,6 @@ msgstr ""
msgid "Profiles|This emoji and message will appear on your profile and throughout the interface."
msgstr ""
msgid "Profiles|This feature is experimental and translations are not complete yet"
msgstr ""
msgid "Profiles|This information will appear on your profile"
