Update the feature change workflow

1 files changed, 37 insertions, 19 deletions

diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md
index b5b325683a3..cb658b85ea4 100644
--- a/doc/development/documentation/feature-change-workflow.md
+++ b/doc/development/documentation/feature-change-workflow.md
@@ -2,23 +2,23 @@
 description: How to add docs for new or enhanced GitLab features.
 ---
 
-# Documentation process at GitLab
+# Documentation Process for Feature Changes
 
 At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
 
 - **Developers**: Author/update documentation in the same MR as their code, and
 merge it by the feature freeze for the assigned milestone. Request technical writer
-assistance if needed.
+assistance if needed. Other developers typically act as reviewers.
 - **Product Managers** (PMs): In the issue for all new and enhanced features,
 confirm the documentation requirements, plus the mentioned feature description
 and use cases, which can be reused in docs. They can bring in a technical
-writer for discussion or help, and can be called upon themselves as a doc reviewer.
+writer for discussion or collaboration, and can be called upon themselves as a doc reviewer.
 - **Technical Writers**: Review doc requirements in issues, track issues and MRs
 that contain docs changes, help with any questions throughout the authoring/editing process,
-and review all new and updated docs content after it's merged (unless a pre-merge
-review request is made).
+work on special projects related to the documentation, and review all new and updated
+docs content after it's merged (unless a pre-merge review request is made).
 
-Beyond this process, any member of the GitLab community can also author documentation
+Beyond this process, any member of the GitLab community can also author or request documentation
 improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md).
 
 ## When documentation is required
@@ -47,6 +47,9 @@ To follow a consistent workflow every month, documentation changes
 involve the Product Managers, the developer who shipped the feature,
 and the Technical Writing team. Each role is described below.
 
+The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab-ce/raw/template-improvements-for-documentation/.gitlab/issue_templates/Feature%20proposal.md)
+and default merge request template assist with following this process.
+
 ### 1. Product Manager's role
 
 The Product Manager (PM) should confirm or add the following items in the issue:
@@ -56,14 +59,17 @@ The Product Manager (PM) should confirm or add the following items in the issue:
   - What new page, new subsection of an existing page, or other update to an existing page/subsection is needed.
   - Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected.
   - Suggested title of any page or subsection, if applicable.
-- Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone.
+- Add the `Documentation` label to the issue.
+
+Anyone is welcome to draft the items above in the issue, but a product manager must review and update any such content whenever the issue is assigned a specific milestone, and finalize this content by the kickoff. 
 
-Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone. 
+### 2. Developer roles
 
-### 2. Developer's role
+**Authoring**
 
 As a developer, you must ship the documentation with the code of the feature that
 you are creating or updating. The documentation is an essential part of the product.
+Technical writers are happy to help, as requested and planned on a feature by feature basis.
 
 - New and edited docs should be included in the MR introducing the code, and planned
 in the issue that proposed the feature. However, if the new or changed doc requires
@@ -75,15 +81,24 @@ idea or outline, or request any other help, ping the Technical Writer for the re
 [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
 in your issue or MR, or write within `#docs` on the GitLab Slack.
 - The docs must be merged with the code **by the feature freeze date**, otherwise
-- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues -->
+the feature cannot be included with the release.<!-- TODO: Policy for feature-flagged issues -->
+
+**Reviews and merging**
+
+All reviewers can help ensure accuracy, clarity, completeness, and adherence to the plans in the issue, as well as the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
+
+* Prior to merge, documentation changes committed by the developer must be reviewed by:
+  1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
+  2. Optionally: Others involved in the work, such as other devs or the PM.
+  3. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
+This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release.
+  4. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
 
-Prior to merge, documentation changes commited by the developer must be reviewed by:
-* the person reviewing the code and merging the MR.
-* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested.
+* Upon merging, if a technical writer review has not been performed, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review).
 
-After merging, documentation changing are reviewed by:
-* a technical writer (for clarity, structure, grammar, etc).
-* optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
+* After merging, documentation changes are reviewed by:
+  1. The technical writer--**if** their review was not performed prior to the merge.
+  2. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
 Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.
 
 ### 3. Technical Writer's role
@@ -93,13 +108,15 @@ Any party can raise the item to the PM for review at any point: the dev, the tec
 technical writer reviews the listed documentation requirements, which should have
 already been reviewed by the PM. (These are non-blocking reviews; developers should
 not wait to work on docs.)
-- Monitor the documentation needs of issues assigned to the current and next milestone,
-and participate in any needed discussion on docs planning with the dev, PM, and others.
+- Monitors the documentation needs of issues assigned to the current and next milestone
+for their DevOps stage(s), and participate in any needed discussion on docs planning
+with the dev, PM, and others.
 
 **Review**
 - Techncial writers provide non-blocking reviews of all documentation changes,
 typically after the change is merged. However, if the docs are ready in the MR while
-we are awaiting other work in order to merge, the technical writer's review can commence early.
+there's time before the freeze or other dev work required in order to merge,
+the technical writer's review can commence early, on request.
 - The technical writer will confirm that the doc is clear, grammatically correct,
 and discoverable, while avoiding redundancy, bad file locations, typos, broken links,
 etc. The technical writer will review the documentation for the following, which
@@ -109,4 +126,5 @@ the developer and code reviewer should have already made a good-faith effort to
   - Location (make sure the doc is in the correct dir and has the correct name).
   - Syntax, typos, and broken links.
   - Improvements to the content.
+  - Adherence to the plans in the issue.
   - Accordance to the [Documentation Style Guide](styleguide.md) and [structure/template](structure.md).