diff options
Diffstat (limited to '.gitlab')
| -rw-r--r-- | .gitlab/issue_templates/Doc Review.md | 21 | ||||
| -rw-r--r-- | .gitlab/issue_templates/Documentation.md | 73 | ||||
| -rw-r--r-- | .gitlab/issue_templates/Feature proposal.md | 23 | ||||
| -rw-r--r-- | .gitlab/merge_request_templates/Documentation.md | 40 |
4 files changed, 99 insertions, 58 deletions
diff --git a/.gitlab/issue_templates/Doc Review.md b/.gitlab/issue_templates/Doc Review.md new file mode 100644 index 00000000000..2f5b458b758 --- /dev/null +++ b/.gitlab/issue_templates/Doc Review.md @@ -0,0 +1,21 @@ +<!-- 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). --> + + +## References + +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 diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md index b33ed5bcaa8..71902d93e24 100644 --- a/.gitlab/issue_templates/Documentation.md +++ b/.gitlab/issue_templates/Documentation.md @@ -1,54 +1,51 @@ -<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation --> +<!-- -<!-- Mention "documentation" or "docs" in 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/ -<!-- 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 --> +Add the relevant label: -## New doc or update? +- `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 -<!-- Mark either of these boxes: --> +<!-- +* 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?) +--> -### 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 4d4d3bfda15..dd8e125916e 100644 --- a/.gitlab/issue_templates/Feature proposal.md +++ b/.gitlab/issue_templates/Feature proposal.md @@ -1,22 +1,35 @@ ### Problem to solve -<!--- What problem do we solve? --> +<!-- What problem do we solve? --> ### Target audience -<!--- For whom are we doing this? Include either a persona from https://design.gitlab.com/getting-started/personas or define a specific company role. e.a. "Release Manager" or "Security Analyst". Use the persona labels as well https://gitlab.com/groups/gitlab-org/-/labels?utf8=%E2%9C%93&subscribed=&search=persona%3A --> +<!-- For whom are we doing this? Include either a persona from https://design.gitlab.com/getting-started/personas or define a specific company role. e.a. "Release Manager" or "Security Analyst". +Use the persona labels as well https://gitlab.com/groups/gitlab-org/-/labels?utf8=%E2%9C%93&subscribed=&search=persona%3A --> ### 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 + +<!-- What doc pages need to be created or updated across user, admin, and API docs? +What concepts, procedures, or information is needed in each area? Is there an 'old way' to deprecate in docs? + +Product managers: +* By the kickoff, finalize the answers to the bullets above, and also: + * When applicable, specify a new or updated feature name, description, benefits, + and use cases, which may all be used in the documentation or features.yml. + * Specify which use cases or scenarios would benefit from a set of instructions or a guide, + whether unique to a single use case or flexible enough to cover multiple use cases. --> ### What does success look like, and how can we measure that? -<!--- Define both the success metrics and acceptance criteria. Note thet 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..a3e3ff3e3cc 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -1,33 +1,43 @@ -<!--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 --> +<!-- Link related issues below. Insert the issue link or reference after "Closes" if merging this should automatically close it. --> 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_ +- [ ] 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_. ## 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. +2. [ ] Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone. +3. [ ] If EE and CE MRs exist, merge the EE MR first, then the CE MR. +4. [ ] After merging, if there has not been a technical writer review, [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 |