From 43c82b229907c2e8d4ca3161c9dd061fea67a486 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 11 Jan 2019 02:41:02 +0000 Subject: [PATCH 01/48] Add documentation items to Feature Request issue template --- .gitlab/issue_templates/Feature proposal.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 639a236631d..53dd423d14c 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -4,7 +4,8 @@ ### Target audience - + ### Further details @@ -14,6 +15,12 @@ +### Documentation + + + ### What does success look like, and how can we measure that? From 6d1d5e33bac508833cb7b4422e81c6e33b72e3df Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 11 Jan 2019 03:26:32 +0000 Subject: [PATCH 02/48] Rewrite Documentation issue template --- .gitlab/issue_templates/Documentation.md | 67 +++++++++++------------- 1 file changed, 31 insertions(+), 36 deletions(-) diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index b33ed5bcaa8..663e6f33c40 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -1,54 +1,49 @@ - + +* Mention "documentation" or "docs" as part of the issue title - +* Use this description 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. + +* For issues related to features of the docs.gitlab.com site, see + https://gitlab.com/gitlab-com/gitlab-docs/issues/ - +* For information about documentation content and process, see + https://docs.gitlab.com/ee/development/documentation/ --> -- [ ] Documents Feature A -- [ ] Follow-up from: #XXX, !YYY +### Type of issue -## New doc or update? +- [ ] Correction or clarification needed +- [ ] New doc or section needed +- [ ] Rewrite of doc or section needed +- [ ] Restructure or other broader improvements +- [ ] Other + +### Problem to solve - + -- [ ] New documentation -- [ ] Update existing documentation +### Target audience -## Checklists + -### Product Manager +### Further details - + -- [ ] Add the correct labels -- [ ] Add the correct milestone -- [ ] Indicate the correct document/directory for this feature -- [ ] Fill the doc blurb below +### Proposal -#### Documentation blurb + - +### Who can address the issue -- Doc **title** + - +### Other links/references -- Feature **overview/description** - - - -- Feature **use cases** - - - -### Developer - - - -- [ ] 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 + /label ~Documentation From 19561b14fedb10828d49b721a34e7e6ea23ab4df Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 11 Jan 2019 04:04:02 +0000 Subject: [PATCH 03/48] Update Documentation MR template --- .../merge_request_templates/Documentation.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 8b7e7119790..7badd748261 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -1,33 +1,34 @@ - + + - - + ## What does this MR do? - + ## Related issues - + Closes ## Author's checklist -- [ ] [Apply the correct labels and milestone](https://docs.gitlab.com/ee/development/documentation/workflow.html#2-developer-s-role-in-the-documentation-process) -- [ ] 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_ +- [ ] Use the Style Guide, as needed. https://docs.gitlab.com/ee/development/documentation/styleguide.html +- [ ] Link the document to and from the higher-level index page. +- [ ] Link the document to and from other subject-related docs, as appropriate. +- [ ] Apply the Documentation label and intended milestone, if known. +- [ ] [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_. ## 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 +- [ ] Optional review by a subject-matter expert, if the author has one in mind. +- [ ] Review by MR assignee for clarity and GitLab style (required). +- [ ] Technical writer review (optional). You can mention the writer listed for the applicable DevOps stage https://about.gitlab.com/handbook/product/categories/#devops-stages +- [ ] If EE and CE MRs exist, merge the EE MR first, then the CE MR. +- [ ] Merge. +- [ ] Mention the the technical writer listed for the applicable DevOps stage if they have not already reviewed. /label ~Documentation From 103243c9f9fcc46250fe2ce1bee5fba44743ac1a Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 18:10:07 +0000 Subject: [PATCH 04/48] Updates to Documentation.md --- .gitlab/issue_templates/Documentation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index 663e6f33c40..98077338def 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -1,7 +1,5 @@ - -### Target audience - - + ### Further details - + ### Proposal - + ### Who can address the issue From 94298f2d84983f607208b0cfdbb777c457de95ab Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 18:21:53 +0000 Subject: [PATCH 06/48] Apply suggestion to .gitlab/issue_templates/Feature proposal.md --- .gitlab/issue_templates/Feature proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 53dd423d14c..1199d5e62b0 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -4,7 +4,7 @@ ### Target audience - ### Further details From 1f4ecf2a71af4731a72e16f9e5fa878df05623d1 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 19:37:24 +0000 Subject: [PATCH 07/48] Updates to Documentation.md --- .../merge_request_templates/Documentation.md | 29 ++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 7badd748261..9071146b366 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -16,19 +16,28 @@ Closes ## Author's checklist -- [ ] Use the Style Guide, as needed. https://docs.gitlab.com/ee/development/documentation/styleguide.html -- [ ] Link the document to and from the higher-level index page. -- [ ] Link the document to and from other subject-related docs, as appropriate. -- [ ] Apply the Documentation label and intended milestone, if known. +- [ ] 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, as appropriate. +- [ ] Apply the ~Documentation label and intended milestone. - [ ] [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_. ## Review checklist -- [ ] Optional review by a subject-matter expert, if the author has one in mind. -- [ ] Review by MR assignee for clarity and GitLab style (required). -- [ ] Technical writer review (optional). You can mention the writer listed for the applicable DevOps stage https://about.gitlab.com/handbook/product/categories/#devops-stages -- [ ] If EE and CE MRs exist, merge the EE MR first, then the CE MR. -- [ ] Merge. -- [ ] Mention the the technical writer listed for the applicable DevOps stage if they have not already reviewed. +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 expert 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. +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 ` 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, create an issue for one with labels ~docs-review and ~Documentation, a link to this MR, and assign it to the technical writer for the [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). /label ~Documentation From a0aa904a05d60736560418419f42c103812cbe24 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 19:40:31 +0000 Subject: [PATCH 08/48] Apply suggestion to .gitlab/issue_templates/Feature proposal.md --- .gitlab/issue_templates/Feature proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 1199d5e62b0..01eabde604e 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -17,7 +17,7 @@ or define a specific company role. e.a. "Release Manager" or "Security Analyst" ### Documentation - From 9dbda559c2b93cfe1d7da150906d1f6cf1a46de7 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 20:45:41 +0000 Subject: [PATCH 09/48] Create Doc Review template --- .gitlab/issue_templates/Doc Review.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 .gitlab/issue_templates/Doc Review.md diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md new file mode 100644 index 00000000000..4488bc4430f --- /dev/null +++ b/.gitlab/issue_templates/Doc Review.md @@ -0,0 +1,15 @@ +<--! This issue is to ensure the quality of documentation content that is merged + without a technical writer review. --> + +<--! NOTE: Please add a DevOps stage label (format `devops:abc`) and assign the technical writer who is + [listed for that stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). --> + + +Merged MR: + +Related issue: + +Notes or questions for technical writer: + + +/label ~Documentation ~docs-review \ No newline at end of file From 6d340e148e504fb53fd79a3b5c1f2916a123afe6 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 20:53:05 +0000 Subject: [PATCH 10/48] Update Doc Review template --- .gitlab/issue_templates/Doc Review.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md index 4488bc4430f..2f5b458b758 100644 --- a/.gitlab/issue_templates/Doc Review.md +++ b/.gitlab/issue_templates/Doc Review.md @@ -1,15 +1,21 @@ -<--! This issue is to ensure the quality of documentation content that is merged + -<--! NOTE: Please add a DevOps stage label (format `devops:abc`) and assign the technical writer who is + -Merged MR: +## References -Related issue: +Merged MR with doc content: + +Related issue(s): + +## Details Notes or questions for technical writer: +1. + /label ~Documentation ~docs-review \ No newline at end of file From b2c6058a499d707cec84e6da552dfa6ee1b3bbd4 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 20:58:27 +0000 Subject: [PATCH 11/48] Update Documentation template --- .gitlab/merge_request_templates/Documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 9071146b366..1cdb1e636f0 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -17,7 +17,7 @@ Closes ## Author's checklist - [ ] 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, as appropriate. +- [ ] Link docs to and from the higher-level index page, plus other related docs where helpful. - [ ] Apply the ~Documentation label and intended milestone. - [ ] [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_. @@ -27,7 +27,7 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to **1. Primary Reviewer** -* [ ] Review by a code reviewer or other selected expert to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. +* [ ] 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** @@ -38,6 +38,6 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to 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. 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 ` 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, create an issue for one with labels ~docs-review and ~Documentation, a link to this MR, and assign it to the technical writer for the [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). +4. [ ] After merging, 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?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal). /label ~Documentation From 343534f40fa1b3babd2694a6437c7cb7ef43e0b6 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 21:17:54 +0000 Subject: [PATCH 12/48] Updates to Feature proposal.md --- .gitlab/issue_templates/Feature proposal.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 01eabde604e..adf302996f0 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -1,6 +1,6 @@ ### Problem to solve - + ### Target audience @@ -9,21 +9,28 @@ or define a specific company role. e.a. "Release Manager" or "Security Analyst" ### Further details - + ### Proposal - + ### Documentation - + ### What does success look like, and how can we measure that? - + ### Links / references From 81e5f80e88622e93bf6e05a266fd7428a35d1d5a Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 21:20:27 +0000 Subject: [PATCH 13/48] Minor edits to Feature proposal template --- .gitlab/issue_templates/Feature proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index adf302996f0..5987d35a3d2 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -19,7 +19,7 @@ or define a specific company role. e.a. "Release Manager" or "Security Analyst" +the feature cannot be included with the release. -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. +**Reviews and merging** -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). +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. + +* 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 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). From 75cf4bdf933c0d13f2ebfda83a098170e05f6108 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 17 Jan 2019 23:07:01 +0000 Subject: [PATCH 16/48] Update improvement workflow --- .../documentation/improvement-workflow.md | 41 +++++++++++++------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index ef6392c6f7f..24de3c275c3 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/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,25 @@ 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. -The technical writing team reviews changes after they are merged, unless a prior -review is requested. +**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: Technical writer review. 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). + +**3. Maintainer** + +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 ` 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, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review). ## 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. From c4d1aa97f63e1ad59fcb3676cb9e612af8e3bc18 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 18 Jan 2019 04:13:39 +0000 Subject: [PATCH 17/48] Additional edits to feature workflow --- .../documentation/feature-change-workflow.md | 39 +++++++++---------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index cb658b85ea4..d1815a9d422 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -45,20 +45,21 @@ so that we can ensure the more time-sensitive doc updates are merged with code b 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. +and the technical writer for the DevOps stage. 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. +and default merge request template will assist you with following this process. ### 1. Product Manager's role The Product Manager (PM) should confirm or add the following items in the issue: -- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md). +- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md) (if applicable). - The documentation requirements for the developer working on the docs. - - 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. + - What should the docs guide and enable the user to understand and accomplish? + - To this end, what new page(s) are needed, if any? What pages/subsections need updates? For any guide or instruction set, should it help address one or more use cases? + - Consider user, admin, and API doc changes and additions. Consider whether we need to update a previously recommended workflow, or if we should link the new feature from various relevant places. Consider all ways documentation should be affected. + - Include suggested titles of any pages or subsections, if applicable. - 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. @@ -69,13 +70,15 @@ Anyone is welcome to draft the items above in the issue, but a product manager m 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. +Technical writers are happy to help, as requested and planned on an issue-by-issue 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 extensive collaboration or conversation, a separate, linked issue can be used for the planning process. +We are trying to avoid using a separate MR, so the docs stay with the code, but the +Technical Writing team is interested in discussing any potential exceptions that may be suggested. - Use the [Documentation guidelines](index.md), as well as other resources linked from there, -including the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +including the Documentation [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 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) @@ -104,27 +107,23 @@ Any party can raise the item to the PM for review at any point: the dev, the tec ### 3. Technical Writer's role **Planning** -- Once an issue contains a Documentation label and an upcoming milestone, a -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.) -- 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 +- The technical writer monitors the documentation needs of issues assigned to the current and next milestone +for their DevOps stage(s), and participates in any needed discussion on docs planning with the dev, PM, and others. +- The technical writer will review these again upon the kickoff and provide feedback, as needed. +This is not a blocking review and developers should not wait to work on docs. **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 -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. +there's time before the freeze, 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 the developer and code reviewer should have already made a good-faith effort to ensure: - Clarity. - - Relevance (make sure the content is appropriate given the impact of the feature). - - Location (make sure the doc is in the correct dir and has the correct name). + - Adherence to the plans and goals in the issue. + - Location (make sure the docs are in the correct directorkes 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). + - Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc. From 582d4d8001b0ffb995e075fa857b18e1a613a1b3 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 23 Jan 2019 03:03:16 +0000 Subject: [PATCH 18/48] Edits to Doc Review template --- .gitlab/issue_templates/Doc Review.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md index 2f5b458b758..dd5efcb9094 100644 --- a/.gitlab/issue_templates/Doc Review.md +++ b/.gitlab/issue_templates/Doc Review.md @@ -1,13 +1,14 @@ - + - ## References -Merged MR with doc content: +Merged MR that introduced documentation requiring review: Related issue(s): @@ -18,4 +19,4 @@ Notes or questions for technical writer: 1. -/label ~Documentation ~docs-review \ No newline at end of file +/label ~Documentation ~docs-review From 04fea355d85552db7fcd7cda86d01adc3abee3dd Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 23 Jan 2019 05:27:44 +0000 Subject: [PATCH 19/48] Edits to Documentation issue template --- .gitlab/issue_templates/Documentation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index 71902d93e24..50b6485b628 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -1,6 +1,6 @@ ### Proposal From 4cbffdf8c8696a764f767f952b5881c484b382b2 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 23 Jan 2019 05:43:03 +0000 Subject: [PATCH 20/48] Update Feature proposal template based on feedback --- .gitlab/issue_templates/Feature proposal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index dd8e125916e..944c15dc339 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -4,7 +4,7 @@ ### Target audience - ### Further details @@ -18,7 +18,7 @@ Use the persona labels as well https://gitlab.com/groups/gitlab-org/-/labels?utf ### Documentation +If applicable, specify a new or updated feature name, description, benefits, and use cases, which may all be used in the documentation or features.yml. +Which use cases or scenarios would benefit from a set of instructions or a guide, whether unique to each use case or flexible enough to cover multiple use cases. --> ### What does success look like, and how can we measure that? From ad8b8aa98c180fae478984529c0bafdb4cc43a74 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 30 Jan 2019 17:48:08 +0000 Subject: [PATCH 25/48] Add more detail on deciding when to have TW review --- .../documentation/feature-change-workflow.md | 42 ++++++++++++------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 8629f62ffdf..afb92b35f4b 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -56,13 +56,16 @@ The Product Manager (PM) should confirm or add the following items in the issue: - New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md) (if applicable). - The documentation requirements for the developer working on the docs. - - What should the docs guide and enable the user to understand and accomplish? - - To this end, what new page(s) are needed, if any? What pages/subsections need updates? For any guide or instruction set, should it help address one or more use cases? - - Consider user, admin, and API doc changes and additions. Consider whether we need to update a previously recommended workflow, or if we should link the new feature from various relevant places. Consider all ways documentation should be affected. + - What concepts and procedures should the docs guide and enable the user to understand and accomplish? + - To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions. + - For any guide or instruction set, should it help address one or more use cases? + - Consider whether we need to update a previously recommended workflow, and if we should link the new feature from various relevant places. Consider all ways documentation should be affected. - Include suggested titles of any pages or subsections, if applicable. - 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 any such content whenever the issue is assigned a specific milestone. +- Finalize this content by the kickoff. ### 2. Developer roles @@ -72,10 +75,15 @@ As a developer, you must ship the documentation with the code of the feature tha 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 an issue-by-issue 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 -extensive collaboration or conversation, a separate, linked issue can be used for the planning process. -We are trying to avoid using a separate MR, so the docs stay with the code, but the +Follow the process below unless otherwise agreed with the product manager and technical writer for a given issue: + +- Include any new and edited docs in the MR introducing the code. +- Use the Documentation requirements confirmed by the Product Manager in the +issue. Discuss any ideas or changes to these requirements in the issue, before you begin, +and in the MR, once you begin work. + - If the new or changed doc requires extensive collaboration or conversation, a separate, +linked issue can be used for the planning process. + - We are trying to avoid using a separate MR, so that the docs stay with the code, but the Technical Writing team is interested in discussing any potential exceptions that may be suggested. - Use the [Documentation guidelines](index.md), as well as other resources linked from there, including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). @@ -91,11 +99,17 @@ the feature cannot be included with the release. + content that was merged without one. --> - -Closes + ## Author's checklist From b0c192b78b59ba5a9fb3ecbbe6c7912a47596ed0 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 6 Feb 2019 04:10:45 +0000 Subject: [PATCH 28/48] Remove numbered list placeholder --- .gitlab/issue_templates/Doc Review.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md index 59fc08996b7..71597332210 100644 --- a/.gitlab/issue_templates/Doc Review.md +++ b/.gitlab/issue_templates/Doc Review.md @@ -16,7 +16,5 @@ Related issue(s): Context, questions, or other notes for technical writer: -1. - /label ~Documentation ~docs-review From 81fd8131ad663b7735047816f6e02ae18420452a Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 6 Feb 2019 04:15:16 +0000 Subject: [PATCH 29/48] Updates to doc review Details section --- .gitlab/issue_templates/Doc Review.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md index 71597332210..14ab0c82d59 100644 --- a/.gitlab/issue_templates/Doc Review.md +++ b/.gitlab/issue_templates/Doc Review.md @@ -12,9 +12,9 @@ Merged MR that introduced documentation requiring review: Related issue(s): -## Details +## Further Details -Context, questions, or other notes for technical writer: + /label ~Documentation ~docs-review From 53840eacc9e79a5338e30ff7b0d9a58e6e3686cb Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 7 Feb 2019 03:29:03 +0000 Subject: [PATCH 30/48] Simplify doc work discussion in feature-change-workflow.md --- doc/development/documentation/feature-change-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index afb92b35f4b..b204daec6b0 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -79,8 +79,7 @@ Follow the process below unless otherwise agreed with the product manager and te - Include any new and edited docs in the MR introducing the code. - Use the Documentation requirements confirmed by the Product Manager in the -issue. Discuss any ideas or changes to these requirements in the issue, before you begin, -and in the MR, once you begin work. +issue and discuss any further doc plans or ideas as needed. - If the new or changed doc requires extensive collaboration or conversation, a separate, linked issue can be used for the planning process. - We are trying to avoid using a separate MR, so that the docs stay with the code, but the @@ -92,7 +91,8 @@ 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. +the feature cannot be included with the release. A policy for documenting feature-flagged +issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813). **Reviews and merging** From 53ea8b1c40cc16d88bf7faa7a4490a13c60f9c13 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 7 Feb 2019 20:52:44 +0000 Subject: [PATCH 31/48] Remove unnecessary mentions of milestone and EE vs CE --- .gitlab/merge_request_templates/Documentation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index a163cd8c0c6..c2067ff54cd 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -16,8 +16,7 @@ - [ ] 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 and intended milestone. -- [ ] [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_. +- [ ] Apply the ~Documentation label. ## Review checklist From 912195ea1f8c14df2be8e500e5e702786fab99a9 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 7 Feb 2019 21:02:43 +0000 Subject: [PATCH 32/48] Update Doc issue template to use /label for types --- .gitlab/issue_templates/Documentation.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index 50b6485b628..6276176c872 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -11,14 +11,23 @@ ### Type of issue -Add the relevant label: + + + + + + + + + + + -- `docs:fix` - Correction or clarification needed. -- `docs:new` - New doc needed to cover a new topic or use case. -- `docs:improvement` - Improving an existing doc; e.g. adding a diagram, adding or rewording text, resolving redundancies, cross-linking, etc. -- `docs:revamp` - Review a page or group of pages in order to plan and implement major improvements/rewrites. -- `docs:other` - Anything else. - ### Problem to solve - - - - - ### Problem to solve From 8198833a130ce5b809d86aa8fa3f27882a674191 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 8 Feb 2019 02:53:58 +0000 Subject: [PATCH 34/48] Update Documentation MR template to remove most of the language around milestones --- .gitlab/merge_request_templates/Documentation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index c2067ff54cd..ba9624aeeab 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -33,8 +33,7 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to **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 of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into ` unless this change is not required for the release. In that case, simply change the milestone. -1. [ ] If EE and CE MRs exist, merge the EE MR first, then the CE MR. -1. [ ] After merging, 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). +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 From 30b4b42e2f06cd3a97395ceae4f533dfeebc0ecb Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 8 Feb 2019 18:15:41 +0000 Subject: [PATCH 35/48] Add Documentation requirements section --- .../documentation/feature-change-workflow.md | 44 ++++++++++++++----- 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index b204daec6b0..74339db7a79 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -41,6 +41,27 @@ When revamping documentation, if unrelated to the feature change, this should be in its own MR (using the [documentation improvement workflow](improvement-workflow.md)) so that we can ensure the more time-sensitive doc updates are merged with code by the freeze. +## Documentation requirements + +Requirements for the documentation of a feature should be included as part of the +issue for planning that feature, in a Documentation section within the issue description. + +This section is provided as part of the Feature Proposal template and should be added +to the issue if it is not already present. + +Anyone can add these details, but the product manager who assigns the issue to a specific release +milestone will ensure these details are present and finalized by the time of that milestone's kickoff. +Developers, technical writers, and others may help further refine this plan at any time. + +### Details to include + +- What concepts and procedures should the docs guide and enable the user to understand or accomplish? +- To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions. +- For any guide or instruction set, should it help address a single use case, or be flexible to address a certain range of use cases? +- Do we need to update a previously recommended workflow? Should we link the new feature from various relevant locations? Consider all ways documentation should be affected. +- Are there any key terms or task descriptions that should be included so that the docs are found in relevant searches? +- Include suggested titles of any pages or subsections, if applicable. + ## Documenting a new or changed feature To follow a consistent workflow every month, documentation changes @@ -52,20 +73,19 @@ and default merge request template will assist you with following this process. ### 1. Product Manager's role -The Product Manager (PM) should confirm or add the following items in the issue: +For issues requiring any new or updated documentation, the Product Manager (PM) +must: -- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md) (if applicable). -- The documentation requirements for the developer working on the docs. - - What concepts and procedures should the docs guide and enable the user to understand and accomplish? - - To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions. - - For any guide or instruction set, should it help address one or more use cases? - - Consider whether we need to update a previously recommended workflow, and if we should link the new feature from various relevant places. Consider all ways documentation should be affected. - - Include suggested titles of any pages or subsections, if applicable. -- Add the `Documentation` label to the issue. +- Add the `Documentation` label. +- Confirm or add the [documentation requirements](#documentation-requirements). +- Ensure the issue contains any new or updated feature name, overview/description, +and use cases, as required per the [documentation structure and template](structure.md), when applicable. -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. -- Finalize this content by the kickoff. +Everyone is encouraged to draft the requirements in the issue, but a product manager will +do the following: + +- When the issue is assigned a release milestone, review and update the Documentation details. +- By the kickoff, finalizie the Documentation details. ### 2. Developer roles From a9326cfa279edf1ae6ffa7708cdd38ee78e48b76 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 8 Feb 2019 18:18:47 +0000 Subject: [PATCH 36/48] Update Documentation section to include link to new Documentation Requirements section in docs --- .gitlab/issue_templates/Feature proposal.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 3cd800907a3..abfbef4b2b0 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -39,11 +39,8 @@ Existing personas are: (copy relevant personas out of this comment, and delete a ### Documentation - + ### What does success look like, and how can we measure that? From 473a71e6e00b91ccc038bf327ac3a12a74de37c2 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 8 Feb 2019 18:28:20 +0000 Subject: [PATCH 37/48] Update labels in Type of issue section --- .gitlab/issue_templates/Documentation.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index 00054138473..c0919aeeda4 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -11,22 +11,13 @@ ### Type of issue - - - - - - - - - - - + + + + + + ### Problem to solve From 7ba1ff926f2c63f6f314d5e46e454e54480cf2d3 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 11 Feb 2019 19:51:56 +0000 Subject: [PATCH 38/48] Update PROCESS.md to account for latest documentation policies --- PROCESS.md | 27 ++++++--------------------- 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 7fdac098807..7728babde08 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -157,7 +157,11 @@ 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). +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, it can +be planned via a follow-up issue for doc review, and another MR if needed. +Regardless, complete docs must be merged with code by the freeze. #### What happens if these deadlines are missed? @@ -186,8 +190,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 @@ -202,23 +204,6 @@ 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 @@ -227,7 +212,7 @@ 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 +* [Essential documentation improvements](https://docs.gitlab.com/ee/development/documentation/workflow.html) 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 From 49736c078e1529322d72eed6730493f9aedc3784 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 11 Feb 2019 20:39:30 +0000 Subject: [PATCH 39/48] Improvement to language on documentation to cherry-pick after freeze --- PROCESS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 7728babde08..74b8440bc56 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -210,11 +210,11 @@ 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 -* [Essential documentation improvements](https://docs.gitlab.com/ee/development/documentation/workflow.html) 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 From 62f65a6d023509a33fbbcbe2f2682d03b838702c Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 11 Feb 2019 21:19:06 +0000 Subject: [PATCH 40/48] Update Dangerfile per updated Technical Writing review policy --- danger/documentation/Dangerfile | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/danger/documentation/Dangerfile b/danger/documentation/Dangerfile index 188331cc87c..a9cac9c7d40 100644 --- a/danger/documentation/Dangerfile +++ b/danger/documentation/Dangerfile @@ -14,34 +14,34 @@ end docs_paths_to_review = docs_paths_requiring_review(helper.all_changed_files) 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 decided 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) | | ------------ | ------------------------------------------------------------ | | `@marcia` | ~Create ~Release + ~"development guidelines" | -| `@axil` | ~Distribution ~Gitaly ~Gitter ~Monitor ~Package ~Secure | +| `@axil` | ~Distribution ~Gitaly ~Gitter ~Monitor ~Package ~Secure | | `@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** -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. +- 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** + +- 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') From e1a1ca0ed81d6212737f11e5c3697d438e013409 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 14 Feb 2019 14:59:51 +0000 Subject: [PATCH 41/48] Edits to feature-change-workflow.md --- .../documentation/feature-change-workflow.md | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 74339db7a79..41068b5cb6b 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -25,10 +25,10 @@ improvements that are not associated with a new or changed feature. See the [Doc Documentation must be delivered whenever: -- A new or enhanced feature is shipped that impacts the user/admin experience -- There are changes to the UI or API -- A process, workflow, or previously documented feature is changed -- A feature is deprecated or removed +- A new or enhanced feature is shipped that impacts the user/admin experience. +- There are changes to the UI or API. +- A process, workflow, or previously documented feature is changed. +- A feature is deprecated or removed. Documentation is not required when a feature is changed on the backend only and does not directly affect the way that any user or @@ -41,7 +41,7 @@ When revamping documentation, if unrelated to the feature change, this should be in its own MR (using the [documentation improvement workflow](improvement-workflow.md)) so that we can ensure the more time-sensitive doc updates are merged with code by the freeze. -## Documentation requirements +## Documentation requirements in feature issues Requirements for the documentation of a feature should be included as part of the issue for planning that feature, in a Documentation section within the issue description. @@ -87,9 +87,9 @@ do the following: - When the issue is assigned a release milestone, review and update the Documentation details. - By the kickoff, finalizie the Documentation details. -### 2. Developer roles +### 2. Developer and maintainer roles -**Authoring** +#### 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. @@ -114,11 +114,12 @@ in your issue or MR, or write within `#docs` on the GitLab Slack. the feature cannot be included with the release. A policy for documenting feature-flagged issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813). -**Reviews and merging** +#### 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. 1. Optionally: Others involved in the work, such as other devs or the PM. 1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge. @@ -131,23 +132,35 @@ the maintainer can merge the current doc changes (if complete) and create a foll - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR. 1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. -- 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). +- 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) +if one was not already created by the developer or reviewer. - 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). + + 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 -**Planning** +#### Planning + - The technical writer monitors the documentation needs of issues assigned to the current and next milestone for their DevOps stage(s), and participates in any needed discussion on docs planning with the dev, PM, and others. - The technical writer will review these again upon the kickoff and provide feedback, as needed. This is not a blocking review and developers should not wait to work on docs. -**Review** +#### Collaboration + +By default, the developer will work on documentation changes independently, but +the developer, PM, or technicial writer can propose a broader collaboration for +any given issue. + +Additionally, technical writers are available for questions at any time. + +#### Review + - Techncial writers provide non-blocking reviews of all documentation changes, before or after the change is merged. However, if the docs are ready in the MR while there's time before the freeze, the technical writer's review can commence early, on request. From 2f66d23d938e995fab3f599adc8b03d82c805486 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 14 Feb 2019 15:06:49 +0000 Subject: [PATCH 42/48] Fix typo and updatee tech writer planning section --- doc/development/documentation/feature-change-workflow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 41068b5cb6b..dac0021a4b8 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -146,9 +146,9 @@ Any party can raise the item to the PM for review at any point: the dev, the tec #### Planning - The technical writer monitors the documentation needs of issues assigned to the current and next milestone -for their DevOps stage(s), and participates in any needed discussion on docs planning +for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement with the dev, PM, and others. -- The technical writer will review these again upon the kickoff and provide feedback, as needed. +- The technical writer will review these requirements again upon the kickoff and provide feedback, as needed. This is not a blocking review and developers should not wait to work on docs. #### Collaboration From 23b781057bb5bc5ea9b7c6abb87b7cad0db28793 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 14 Feb 2019 15:15:47 +0000 Subject: [PATCH 43/48] Remove numbers from headers --- doc/development/documentation/feature-change-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index dac0021a4b8..e75d46ea62b 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -71,7 +71,7 @@ and the technical writer for the DevOps stage. 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 will assist you with following this process. -### 1. Product Manager's role +### Product Manager's role For issues requiring any new or updated documentation, the Product Manager (PM) must: @@ -87,7 +87,7 @@ do the following: - When the issue is assigned a release milestone, review and update the Documentation details. - By the kickoff, finalizie the Documentation details. -### 2. Developer and maintainer roles +### Developer and maintainer roles #### Authoring @@ -141,7 +141,7 @@ if one was not already created by the developer or reviewer. 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 +### Technical Writer's role #### Planning From a2449492d0fd3f41abb86204ebbcd221b4aa994a Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Thu, 14 Feb 2019 15:40:57 +0000 Subject: [PATCH 44/48] Add better links on documentation process to PROCESS.md --- PROCESS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 74b8440bc56..ad74ead8aab 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -156,12 +156,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) +[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, it can -be planned via a follow-up issue for doc review, and another MR if needed. -Regardless, complete docs must be merged with code by the freeze. +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? From f0c1bae7dbb6e232f4699b91b98444686dc81db8 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 18 Feb 2019 21:10:26 +0000 Subject: [PATCH 45/48] Update improvement-workflow re who creates and confirms tech writer review issues --- doc/development/documentation/improvement-workflow.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index 2fd295fba4b..fbc3cf806ee 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -47,13 +47,14 @@ The process can involve the following parties/phases, and is replicated in the ` **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** 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 ` 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, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review). +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 From d4aa26176dcce8b862d33fce25e48bd3dc2cca8c Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 18 Feb 2019 21:20:40 +0000 Subject: [PATCH 46/48] Update feature-change-workflow to clarify who can create follow-up TW review issue --- doc/development/documentation/feature-change-workflow.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index e75d46ea62b..0a257d67628 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -118,7 +118,7 @@ issues is forthcoming and you are welcome to join the [discussion](https://gitla 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: +- **Prior to merging**, documentation changes committed by the developer must be reviewed by: 1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness. 1. Optionally: Others involved in the work, such as other devs or the PM. @@ -130,10 +130,12 @@ and your degree of confidence in having users of an RC use your docs as written. - You can request a review and if there is not sufficient time to complete it prior to the freeze, the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue. - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR. + - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). + - **To request a post-merge 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 link it from the MR that makes the doc change. 1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. -- 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) -if one was not already created by the developer or reviewer. +- Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and +mention the original MR author in the new issue. Alternatively, the mainitainer can ask the MR author to create and link this issue before the MR is merged. - After merging, documentation changes are reviewed by: From f1645c744fcf8677ae14714914c4c4ffb9d5b17e Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Mon, 18 Feb 2019 21:23:25 +0000 Subject: [PATCH 47/48] Update Documentation Dangerfile with small wording change --- danger/documentation/Dangerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/danger/documentation/Dangerfile b/danger/documentation/Dangerfile index a9cac9c7d40..fff4d0e2582 100644 --- a/danger/documentation/Dangerfile +++ b/danger/documentation/Dangerfile @@ -24,7 +24,7 @@ The following files will require a review from the [Technical Writing](https://a * #{docs_paths_to_review.map { |path| "`#{path}`" }.join("\n* ")} -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 decided 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.) +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: From fc3975a553f0dff1a0e20ca35b47e3494e53c62d Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Tue, 19 Feb 2019 18:34:10 +0000 Subject: [PATCH 48/48] Update some headers to remove apostrophes --- .../documentation/feature-change-workflow.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 0a257d67628..eb479b85083 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -16,7 +16,7 @@ writer for discussion or collaboration, and can be called upon themselves as a d - **Technical Writers**: Review doc requirements in issues, track issues and MRs that contain docs changes, help with any questions throughout the authoring/editing process, 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). +docs content, whether before or after it is merged. 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). @@ -30,11 +30,12 @@ Documentation must be delivered whenever: - A process, workflow, or previously documented feature is changed. - A feature is deprecated or removed. +For example, a UI restyling that offers no difference in functionality may require +documentation updates if screenshots are now needed, or need to be updated. + Documentation is not required when a feature is changed on the backend -only and does not directly affect the way that any user or -administrator would interact with GitLab. For example, a UI restyling that offers -no difference in functionality may require documentation updates if screenshots -are now needed, or need to be updated. +only and does not directly affect the way that any user or administrator would +interact with GitLab. NOTE: **Note:** When revamping documentation, if unrelated to the feature change, this should be submitted @@ -71,7 +72,7 @@ and the technical writer for the DevOps stage. 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 will assist you with following this process. -### Product Manager's role +### Product Manager role For issues requiring any new or updated documentation, the Product Manager (PM) must: @@ -143,7 +144,7 @@ mention the original MR author in the new issue. Alternatively, the mainitainer 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. -### Technical Writer's role +### Technical Writer role #### Planning