diff options
Diffstat (limited to '.gitlab')
| -rw-r--r-- | .gitlab/issue_templates/Doc Review.md | 20 | ||||
| -rw-r--r-- | .gitlab/issue_templates/Documentation.md | 75 | ||||
| -rw-r--r-- | .gitlab/issue_templates/Feature proposal.md | 13 | ||||
| -rw-r--r-- | .gitlab/merge_request_templates/Documentation.md | 40 |
4 files changed, 89 insertions, 59 deletions
diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md new file mode 100644 index 00000000000..14ab0c82d59 --- /dev/null +++ b/.gitlab/issue_templates/Doc Review.md @@ -0,0 +1,20 @@ +<!-- This issue requests a technical writer review as required for documentation + content that was merged without one. --> + +<!-- NOTE: Please add a DevOps stage label (format `devops:<stage_name>`) + and assign the technical writer who is + [listed for that stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). --> + + +## References + +Merged MR that introduced documentation requiring review: + +Related issue(s): + +## Further Details + +<!-- Any additional context, questions, or notes for the technical writer. --> + + +/label ~Documentation ~docs-review diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index b33ed5bcaa8..c0919aeeda4 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -1,54 +1,53 @@ -<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation --> +<!-- -<!-- Mention "documentation" or "docs" in the issue title --> +* Use this issue template for suggesting new docs or updates to existing docs. + Note: Doc work as part of feature development is covered in the Feature Request template. + +* For issues related to features of the docs.gitlab.com site, see + https://gitlab.com/gitlab-com/gitlab-docs/issues/ -<!-- Use this description template for new docs or updates to existing docs. --> +* For information about documentation content and process, see + https://docs.gitlab.com/ee/development/documentation/ --> -<!-- Check the documentation structure guidelines for guidance: https://docs.gitlab.com/ee/development/documentation/structure.html--> +### Type of issue -- [ ] Documents Feature A <!-- feature name --> -- [ ] Follow-up from: #XXX, !YYY <!-- Mention related issues, MRs, and epics when available --> +<!-- Un-comment the line for the applicable doc issue type to add its label. + Note that all text on that line is deleted upon issue creation. --> +<!-- /label ~"docs:fix" - Correction or clarification needed. --> +<!-- /label ~"docs:new" - New doc needed to cover a new topic or use case. --> +<!-- /label ~"docs:improvement" - Improving an existing doc; e.g. adding a diagram, adding or rewording text, resolving redundancies, cross-linking, etc. --> +<!-- /label ~"docs:revamp" - Review a page or group of pages in order to plan and implement major improvements/rewrites. --> +<!-- /label ~"docs:other" - Anything else. --> -## New doc or update? +### Problem to solve -<!-- Mark either of these boxes: --> +<!-- Include the following detail as necessary: +* What product or feature(s) affected? +* What docs or doc section affected? Include links or paths. +* Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs? +* Any other ideas or requests? +--> -- [ ] New documentation -- [ ] Update existing documentation +### Further details -## Checklists +<!-- +* Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab? +* Include use cases, benefits, and/or goals for this work. +* If adding content: What audience is it intended for? (What roles and scenarios?) + For ideas, see personas at https://design.gitlab.com/research/personas or the persona labels at + https://gitlab.com/groups/gitlab-org/-/labels?utf8=%E2%9C%93&subscribed=&search=persona%3A +--> -### Product Manager +### Proposal -<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#1-product-manager-s-role-in-the-documentation-process --> +<!-- Further specifics for how can we solve the problem. --> -- [ ] Add the correct labels -- [ ] Add the correct milestone -- [ ] Indicate the correct document/directory for this feature <!-- (ping the tech writers for help if you're not sure) --> -- [ ] Fill the doc blurb below +### Who can address the issue -#### Documentation blurb +<!-- What if any special expertise is required to resolve this issue? --> -<!-- Documentation template: https://docs.gitlab.com/ee/development/documentation/structure.html#documentation-template-for-new-docs --> +### Other links/references -- Doc **title** - - <!-- write the doc title here --> - -- Feature **overview/description** - - <!-- Write the feature overview here --> - -- Feature **use cases** - - <!-- Write the use cases here --> - -### Developer - -<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#2-developer-s-role-in-the-documentation-process --> - -- [ ] Copy the doc blurb above and paste it into the doc -- [ ] Write the tutorial - explain how to use the feature -- [ ] Submit the MR using the appropriate MR description template +<!-- E.g. related GitLab issues/MRs --> /label ~Documentation diff --git a/.gitlab/issue_templates/Feature proposal.md b/.gitlab/issue_templates/Feature proposal.md index 1bb8d33ff63..abfbef4b2b0 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -1,6 +1,6 @@ ### Problem to solve -<!--- What problem do we solve? --> +<!-- What problem do we solve? --> ### Target audience @@ -31,15 +31,20 @@ Existing personas are: (copy relevant personas out of this comment, and delete a ### Further details -<!--- Include use cases, benefits, and/or goals (contributes to our vision?) --> +<!-- Include use cases, benefits, and/or goals (contributes to our vision?) --> ### Proposal -<!--- How are we going to solve the problem? Try to include the user journey! --> +<!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> + +### Documentation + +<!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html +Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements --> ### What does success look like, and how can we measure that? -<!--- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this --> +<!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> ### Links / references diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 8b7e7119790..ba9624aeeab 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -1,33 +1,39 @@ -<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation --> +<!-- Follow the documentation workflow https://docs.gitlab.com/ee/development/documentation/workflow.html --> +<!-- Additional information is located at https://docs.gitlab.com/ee/development/documentation/ --> <!-- Mention "documentation" or "docs" in the MR title --> - -<!-- Use this description template for new docs or updates to existing docs. For changing documentation location use the "Change documentation location" template --> +<!-- For changing documentation location use the "Change documentation location" template --> ## What does this MR do? -<!-- Briefly describe what this MR is about --> +<!-- Briefly describe what this MR is about. --> ## Related issues -<!-- Mention the issue(s) this MR closes or is related to --> - -Closes +<!-- Link related issues below. Insert the issue link or reference after the word "Closes" if merging this should automatically close it. --> ## Author's checklist -- [ ] [Apply the correct labels and milestone](https://docs.gitlab.com/ee/development/documentation/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_ +- [ ] Follow the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html). +- [ ] Link docs to and from the higher-level index page, plus other related docs where helpful. +- [ ] Apply the ~Documentation label. ## Review checklist -- [ ] Your team's review (required) -- [ ] PM's review (recommended, but not a blocker) -- [ ] Technical writer's review (required) -- [ ] Merge the EE-MR first, CE-MR afterwards +All reviewers can help ensure accuracy, clarity, completeness, and adherence to the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html). + +**1. Primary Reviewer** + +* [ ] Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. + +**2. Technical Writer** + +* [ ] Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). + +**3. Maintainer** + +1. [ ] Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review. +1. [ ] Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist. +1. [ ] If there has not been a technical writer review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review). /label ~Documentation |