Merge branch 'psi-cadence-docs' into 'master'

Iteration cadence docs

See merge request gitlab-org/gitlab!62979

doc/user/group/iterations/index.md

@@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - Deployed behind a feature flag, disabled by default.
 > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2.
 > - Enabled on GitLab.com.
-> - Able to be enabled or disabled per-group.
+> - Can be enabled or disabled per-group.
 > - Recommended for production use.
-> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(PREMIUM ONLY)**
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-iterations). **(PREMIUM ONLY)**
 > - Moved to GitLab Premium in 13.9.
 
 Iterations are a way to track issues over a period of time. This allows teams
@@ -32,31 +32,81 @@ In GitLab, iterations are similar to milestones, with a few differences:
 - Iterations require both a start and an end date.
 - Iteration date ranges cannot overlap.
 
+## Iteration cadences
+
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1.
+> - Deployed behind a [feature flag](../../feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). **(PREMIUM SELF)**
+
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
+
+Iteration cadences automate some common iteration tasks. They can be used to
+automatically create iterations every 1, 2, 3, 4, or 6 weeks. They can also
+be configured to automatically roll over incomplete issues to the next iteration.
+
+### Create an iteration cadence
+
+Prerequisites:
+
+- You must have at least the [Developer role](../../permissions.md) for a group.
+
+To create an iteration cadence:
+
+1. On the top bar, select **Menu > Groups** and find your group.
+1. On the left sidebar, select **Issues > Iterations**.
+1. Select **New iteration cadence**.
+1. Fill out required fields, and select **Create iteration cadence**. The cadence list page opens.
+
+## Delete an iteration cadence
+
+Prerequisites:
+
+- You must have at least the [Developer role](../../permissions.md) for a group.
+
+Deleting an iteration cadence also deletes all iterations within that cadence.
+
+To delete an iteration cadence:
+
+1. On the top bar, select **Menu > Groups** and find your group.
+1. On the left sidebar, select **Issues > Iterations**.
+1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete.
+1. Select **Delete cadence** in the confirmation modal.
+
 ## View the iterations list
 
-To view the iterations list, in a group, go to **{issues}** **Issues > Iterations**.
-From there you can create a new iteration or click an iteration to get a more detailed view.
+To view the iterations list, go to **{issues}** **Issues > Iterations**.
+To view all the iterations in a cadence, ordered by descending date, select that iteration cadence.
+From there you can create a new iteration or select an iteration to get a more detailed view.
 
 ## Create an iteration
 
-NOTE:
-You need Developer [permissions](../../permissions.md) or higher to create an iteration.
+Prerequisites:
+
+- You must have at least the [Developer role](../../permissions.md) for a group.
+
+For manually scheduled iteration cadences, you create and add iterations yourself.
 
 To create an iteration:
 
-1. In a group, go to **{issues}** **Issues > Iterations**.
-1. Click **New iteration**.
+1. On the top bar, select **Menu > Groups** and find your group.
+1. On the left sidebar, select **Issues > Iterations**.
+1. Select the three-dot menu (**{ellipsis_v}**) > **Add iteration** for the cadence you want to add to.
 1. Enter the title, a description (optional), a start date, and a due date.
-1. Click **Create iteration**. The iteration details page opens.
+1. Select **Create iteration**. The iteration details page opens.
 
 ## Edit an iteration
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2.
 
-NOTE:
-You need Developer [permissions](../../permissions.md) or higher to edit an iteration.
+Prerequisites:
+
+- You must have at least the [Developer role](../../permissions.md) for a group.
 
-To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit iteration**.
+To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit iteration**.
 
 ## Add an issue to an iteration
 
@@ -76,7 +126,7 @@ The report also shows a breakdown of total issues in an iteration.
 Open iteration reports show a summary of completed, unstarted, and in-progress issues.
 Closed iteration reports show the total number of issues completed by the due date.
 
-To view an iteration report, go to the iterations list page and click an iteration's title.
+To view an iteration report, go to the iterations list page and select an iteration's title.
 
 ### Iteration burndown and burnup charts
 
@@ -99,13 +149,15 @@ and get a more accurate understanding of scope attributable to each label.
 
 To group issues by label:
 
+1. On the top bar, select **Menu > Groups** and find your group.
+1. On the left sidebar, select **Issues > Iterations**.
 1. In the **Group by** dropdown, select **Label**.
 1. Select the **Filter by label** dropdown.
 1. Select the labels you want to group by in the labels dropdown.
    You can also search for labels by typing in the search input.
-1. Click or tap outside of the label dropdown. The page is now grouped by the selected labels.
+1. Select or tap outside of the label dropdown. The page is now grouped by the selected labels.
 
-## Disable iterations **(PREMIUM SELF)**
+## Enable or disable iterations **(PREMIUM SELF)**
 
 GitLab Iterations feature is deployed with a feature flag that is **enabled by default**.
 [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
@@ -129,6 +181,25 @@ Feature.disable(:group_iterations)
 Feature.disable(:group_iterations, Group.find(<group ID>))
 ```
 
+### Enable or disable iteration cadences **(PREMIUM SELF)**
+
+Iteration Cadences feature is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:iterations_cadences)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:iterations_cadences)
+```
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues