Merge branch 'template-improvements-for-documentation' into 'master'

Template and process improvements for documentation

See merge request gitlab-org/gitlab-ce!24315

.gitlab/issue_templates/Doc Review.md

+<!-- This issue requests a technical writer review as required for documentation
+     content that was merged without one. -->
+
+<!-- NOTE: Please add a DevOps stage label (format `devops:<stage_name>`)
+     and assign the technical writer who is
+     [listed for that stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). -->
+
+
+## References
+
+Merged MR that introduced documentation requiring review: 
+
+Related issue(s): 
+
+## Further Details
+
+<!-- Any additional context, questions, or notes for the technical writer. -->
+
+
+/label ~Documentation ~docs-review

.gitlab/issue_templates/Documentation.md

-<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation -->
+<!--
 
-<!-- Mention "documentation" or "docs" in the issue title -->
+* Use this issue template for suggesting new docs or updates to existing docs.
+  Note: Doc work as part of feature development is covered in the Feature Request template.
   
-<!-- Use this description template for new docs or updates to existing docs. -->
+* For issues related to features of the docs.gitlab.com site, see
+     https://gitlab.com/gitlab-com/gitlab-docs/issues/       
 
-<!-- Check the documentation structure guidelines for guidance: https://docs.gitlab.com/ee/development/documentation/structure.html-->
+* For information about documentation content and process, see
+     https://docs.gitlab.com/ee/development/documentation/ -->
 
-- [ ] Documents Feature A <!-- feature name -->
-- [ ] Follow-up from: #XXX, !YYY <!-- Mention related issues, MRs, and epics when available -->
+### Type of issue
 
-## New doc or update?
+<!-- 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. -->
 
-<!-- Mark either of these boxes: -->
+### Problem to solve
 
-- [ ] New documentation
-- [ ] Update existing documentation
+<!-- 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?
+-->
 
-## Checklists
+### Further details
 
-### Product Manager
+<!--
+* 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
+  https://gitlab.com/groups/gitlab-org/-/labels?utf8=%E2%9C%93&subscribed=&search=persona%3A
+-->
 
-<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#1-product-manager-s-role-in-the-documentation-process -->
+### Proposal
 
-- [ ] Add the correct labels
-- [ ] Add the correct milestone
-- [ ] Indicate the correct document/directory for this feature <!-- (ping the tech writers for help if you're not sure) -->
-- [ ] Fill the doc blurb below
+<!-- Further specifics for how can we solve the problem. -->
 
-#### Documentation blurb
+### Who can address the issue
 
-<!-- Documentation template: https://docs.gitlab.com/ee/development/documentation/structure.html#documentation-template-for-new-docs -->
+<!-- What if any special expertise is required to resolve this issue? -->
 
-- Doc **title**
+### Other links/references
 
-    <!-- write the doc title here -->
-
-- Feature **overview/description**
-
-    <!-- Write the feature overview here -->
-
-- Feature **use cases**
-
-    <!-- Write the use cases here -->
-
-### Developer
-
-<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#2-developer-s-role-in-the-documentation-process -->
-
-- [ ] Copy the doc blurb above and paste it into the doc
-- [ ] Write the tutorial - explain how to use the feature
-- [ ] Submit the MR using the appropriate MR description template
+<!-- E.g. related GitLab issues/MRs -->
 
 /label ~Documentation

.gitlab/issue_templates/Feature proposal.md

 ### Problem to solve
 
-<!--- What problem do we solve? -->
+<!-- What problem do we solve? -->
 
 ### Target audience
 
@@ -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. -->
 
 ### Links / references
 

.gitlab/merge_request_templates/Documentation.md

-<!--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).
 
 /label ~Documentation

PROCESS.md

@@ -168,8 +168,12 @@ on behalf of the community member.
 
 Every new feature or change should be shipped with its corresponding documentation
 in accordance with the
-[documentation process](https://docs.gitlab.com/ee/development/documentation/workflow.html)
-and [structure](https://docs.gitlab.com/ee/development/documentation/structure.html).
+[documentation process](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html)
+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?
 
@@ -198,8 +202,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
@@ -214,34 +216,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.
-
-For more information read the process for
-[documentation shipped late](https://docs.gitlab.com/ee/development/documentation/workflow.html#documentation-shipped-late).
-
 ### After the 7th
 
 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

danger/documentation/Dangerfile

@@ -3,20 +3,19 @@
 docs_paths_to_review = helper.changes_by_category[:docs]
 
 unless docs_paths_to_review.empty?
-  message 'This merge request adds or changes files that require a ' \
-    'review from the Docs team.'
+  message 'This merge request adds or changes files that require a review ' \
+    'from the Technical Writing team whether before or after merging.'
 
   markdown(<<~MARKDOWN)
-## Docs review
+## Documentation review
 
-The following files require a review from the Documentation team:
+The following files will require a review from the [Technical Writing](https://about.gitlab.com/handbook/product/technical-writing/) team:
 
 * #{docs_paths_to_review.map { |path| "`#{path}`" }.join("\n* ")}
 
-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:
 
 | Tech writer  | Stage(s)                                                     |
 | ------------ | ------------------------------------------------------------ |
@@ -25,12 +24,13 @@ to be reviewed.
 | `@eread`     | ~Manage ~Configure ~Geo ~Verify                              |
 | `@mikelewis` | ~Plan                                                        |
 
-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.
   MARKDOWN
 
   unless gitlab.mr_labels.include?('Documentation')

doc/development/documentation/improvement-workflow.md

@@ -2,7 +2,7 @@
 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/). 
-- Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
-- 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/). 
+1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
+
+If you need any help to choose the correct place for a doc, discuss a documentation
 idea or outline, or request any other help, ping the Technical Writer for the relevant
 [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
 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)
+using the Documentation template.