Simplify Unleash docs updates

README.md

@@ -144,7 +144,7 @@ Check out [the CONTRIBUTING.md file](./CONTRIBUTING.md) for contribution guideli
 - [A/B testing](https://docs.getunleash.io/feature-flag-tutorials/use-cases/a-b-testing)
 - 2 [environments](https://docs.getunleash.io/reference/environments)
 - Out-of-the-box integrations with popular tools ([Slack](https://docs.getunleash.io/addons/slack), [Microsoft Teams](https://docs.getunleash.io/addons/teams), [Datadog](https://docs.getunleash.io/addons/datadog)) + integrate with anything with [webhooks](https://docs.getunleash.io/addons/webhook)
-- [Dashboard for managing technical debt](https://docs.getunleash.io/reference/technical-debt) and [stale flags](https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-toggles)
+- [Insights for managing technical debt](https://docs.getunleash.io/reference/technical-debt) and [stale flags](https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-flags)
 - API-first: _everything_ can be automated. No exceptions.
 - [12 official client SDKs](https://docs.getunleash.io/reference/sdks#official-sdks), and 10 [community-contributed client SDKs](https://docs.getunleash.io/reference/sdks#community-sdks)
 - Run it via Docker with the [official Docker image](https://hub.docker.com/r/unleashorg/unleash-server) or as a pure Node.js application

frontend/src/component/featureTypes/FeatureTypeEdit/FeatureTypeForm/FeatureTypeForm.tsx

@@ -151,7 +151,7 @@ export const FeatureTypeForm: VFC<FeatureTypeFormProps> = ({
                                 </p>
                                 <br />
                                 <a
-                                    href='https://docs.getunleash.io/reference/feature-toggles#expected-lifetime'
+                                    href='https://docs.getunleash.io/reference/feature-toggles#feature-flag-types'
                                     target='_blank'
                                     rel='noreferrer'
                                 >

frontend/src/component/project/Project/ProjectHealth/ReportTable/ReportCard/ReportCard.tsx

@@ -88,7 +88,7 @@ export const ReportCard = ({ healthReport }: IReportCardProps) => {
                     it will be marked as potentially stale.
                     <Box sx={{ mt: 2 }}>
                         <a
-                            href='https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-toggles'
+                            href='https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-flags'
                             target='_blank'
                             rel='noreferrer'
                         >

src/lib/features/feature-toggle/feature-toggle-controller.ts

@@ -571,7 +571,7 @@ export default class ProjectFeaturesController extends Controller {
                     tags: ['Features'],
                     operationId: 'staleFeatures',
                     summary: 'Mark features as stale / not stale',
-                    description: `This endpoint marks the provided list of features as either [stale](https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-toggles) or not stale depending on the request body you send. Any provided features that don't exist are ignored.`,
+                    description: `This endpoint marks the provided list of features as either [stale](https://docs.getunleash.io/reference/technical-debt#stale-and-potentially-stale-flags) or not stale depending on the request body you send. Any provided features that don't exist are ignored.`,
                     requestBody: createRequestSchema('batchStaleSchema'),
                     responses: {
                         202: emptyResponse,

src/lib/openapi/spec/deprecated-project-overview-schema.ts

@@ -75,7 +75,7 @@ export const deprecatedProjectOverviewSchema = {
             type: 'number',
             example: 50,
             description:
-                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
+                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#project-status) on a scale from 0 to 100",
         },
         environments: {
             type: 'array',

src/lib/openapi/spec/health-overview-schema.ts

@@ -75,7 +75,7 @@ export const healthOverviewSchema = {
         health: {
             type: 'integer',
             description:
-                'The overall [health rating](https://docs.getunleash.io/reference/technical-debt#health-rating) of the project.',
+                'The overall [health rating](https://docs.getunleash.io/reference/technical-debt#project-status) of the project.',
             example: 95,
         },
         environments: {

src/lib/openapi/spec/personal-dashboard-schema.ts

@@ -103,7 +103,7 @@ export const personalDashboardSchema = {
                         example: 50,
                         minimum: 0,
                         description:
-                            "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
+                            "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#project-status) on a scale from 0 to 100",
                     },
                     memberCount: {
                         type: 'integer',

src/lib/openapi/spec/project-insights-schema.ts

@@ -28,7 +28,7 @@ export const projectInsightsSchema = {
                 rating: {
                     type: 'integer',
                     description:
-                        "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
+                        "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#project-status) on a scale from 0 to 100",
                     example: 95,
                 },
                 activeCount: {

src/lib/openapi/spec/project-overview-schema.ts

@@ -76,7 +76,7 @@ export const projectOverviewSchema = {
             type: 'number',
             example: 50,
             description:
-                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
+                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#project-status) on a scale from 0 to 100",
         },
         environments: {
             type: 'array',

src/lib/openapi/spec/project-schema.ts

@@ -29,7 +29,7 @@ export const projectSchema = {
             type: 'number',
             example: 50,
             description:
-                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
+                "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#project-status) on a scale from 0 to 100",
         },
         featureCount: {
             type: 'number',

src/lib/routes/admin-api/project/health-report.ts

@@ -48,7 +48,7 @@ export default class ProjectHealthReport extends Controller {
                     operationId: 'getProjectHealthReport',
                     summary: 'Get a health report for a project.',
                     description:
-                        'This endpoint returns a health report for the specified project. This data is used for [the technical debt dashboard](https://docs.getunleash.io/reference/technical-debt#the-technical-debt-dashboard)',
+                        'This endpoint returns a health report for the specified project. This data is used for [the technical debt insights](https://docs.getunleash.io/reference/technical-debt)',
                     responses: {
                         200: createResponseSchema('healthReportSchema'),
                         ...getStandardResponses(401, 403, 404),

website/docs/reference/change-requests.mdx

@@ -10,61 +10,50 @@ import VideoContent from '@site/src/components/VideoContent.jsx';
 
 :::
 
+## Overview
 
-<VideoContent videoUrls={["https://www.youtube.com/embed/ENUqFVcdr-w"]}/>
-
+Change requests allow you to require an additional approval step before any changes can be made in an environment. This functionality supports the "four-eyes principle", ensuring compliance in industries with strict legal or regulatory requirements.
+
+Change requests also allows you to group changes and apply them at a specific point in time.
 
-Feature flagging is a powerful tool, and because it's so powerful, you sometimes need to practice caution. The ability to have complete control over your production environment comes at the cost of the potential to make mistakes in production. Change requests were introduced in version 4.19.0 to alleviate this fear. Change requests allow you to group changes together and apply them to production at the same time, instead of applying changes directly to production. This allows you to make multiple changes to feature flags and their configuration and status (on/off) all at once, reducing the risk of errors in production.
+Change requests can be enabled on a per-project and per-environment basis. This allows you to differentiate your configurations across different environments, such as production and development.
 
-Our goal is developer efficiency, but we also recognize that we have users and customers in highly regulated industries, governed by law and strict requirements. Therefore, we have added a capability to change requests that will allow you to enforce the _4 eyes principle_.
+<VideoContent videoUrls={["https://www.youtube.com/embed/ENUqFVcdr-w"]}/>
 
-## Change request configuration
+You can require up to 10 approvals for change request. Anyone with project access can create a change request; however, only users with the specific permissions can approve, apply, or skip them. None of the predefined roles have any change request permissions, so you must create [custom project roles](/reference/rbac#custom-project-roles). A user cannot approve their own change request.
 
-The change request configuration can be set up per project, per environment. This means that you can have different change request configurations for different environments, such as production and development. This is useful because different environments may have different requirements, so you can customize the change request configuration to fit those requirements. However, this also means that you cannot change flags across projects in the same change request.
+## Enable change request for a project and environment
 
-Currently there are two configuration options for change requests:
-* **Enable change requests** - This is a boolean value that enables or disables change requests for the project and environment.
-* **Required approvals** - This is an integer value that indicates how many approvals are required before a change request can be applied. Specific permissions are required to approve and apply change requests.
+To enable change requests for a project, do the following:
 
-The change request configuration can be set up in the project settings page:
+1. Open the project and go to **Settings > Change request configuration**.
+2. Toggle **Status** for the enviroment where you want to enable change requests.
+3. Select the required number of approvals.
 
 ![Change request configuration](/img/change-request-configuration.png)
 
-
 ## Change request flow
 
-Once a change request flow is configured for a project and environment, you can no longer directly change the status of a flag. Instead, you will be asked to put your changes into a draft. The change request flow handles the following scenarios:
-
-* Updating the status of a flag in the environment
-* Adding a strategy to the feature flag in the environment
-* Updating a strategy of a feature flag in the environment
-* Deleting a strategy from a feature flag in the environment
-
-The flow can be summarized as follows:
+Once a change request are enabled for a project and environment, you cannot directly change the status and configuration of a feature flag. Instead, changes are grouped into a change request draft.
 
 ![Change request flow](/img/change-request-flow.png)
 
-Once a change is added to a draft, the draft needs to be completed before another change request can be opened. The draft is personal to the user that created the change request draft, until it is sent for review. Once changes are added to draft, the user will have a banner in the top of the screen indicating that a draft exists. The state of a change request can be one of the following:
-
-* **Draft** - The change request is in draft mode, and can be edited by the user that created the draft.
-* **In review** - The change request is in review mode, and can be edited by the user that created the draft. If editing occurs, all current approvals are revoked
-* **Approved** - The change request has been approved by the required number of users.
-* **Scheduled** - The change request has been scheduled and will be applied at the scheduled time (unless there are conflicts, as described in the section on [scheduling change requests](#scheduled-changes)).
-* **Applied** - The change request has been applied to the environment. The feature flag configuration is updated.
-* **Cancelled** - The change request has been cancelled by the change request author or by an admin.
-* **Rejected** - The change request has been rejected by the reviewer or by an admin.
+Once you make the first modification in an environment that has change requests enabled, any subsequent changes must be added to the same draft. This draft remains private to its author until it's submitted for review. While a draft is active, a banner at the top of the screen informs the author that changes are pending.
 
-![Change request banner](/img/change-request-banner.png)
+The lifecycle of a change request includes:
+* **Draft** - The change request is in draft mode, and can be edited by the author.
+* **In review** - The request has been submitted for review. The author can still make edits, but doing so will revoke any existing approvals.
+* **Approved** - The request has received the required number of approvals.
+* **Scheduled** - The request is scheduled to be applied at a future time (assuming no [conflicts](#conflicts)).
+* **Applied** - The changes have been successfully applied to the environment.
+* **Cancelled** - The change request has been cancelled by the author or by an admin.
+* **Rejected** - The change request has been rejected by a reviewer or by an admin.
 
-Once a change request is sent to review by the user who created it, it becomes available for everyone in the change request tab in the project.
+Once submitted, the change request appears in the project's **Change requests** tab. From there, you can view details of the proposed changes, the current status of the request, and the next steps required. Users with sufficient persmissions can approve or reject, and apply or schedule the changes.
 
-From here, you can navigate to the change request overview page. This page will give you information about the changes the change request contains, the state the change request is in, and what action needs to be taken next.
+![Change request overview](/img/change-request-overview.png)
 
-![Change request banner](/img/change-request-overview.png)
-
-From here, if you have the correct permissions, you can approve and schedule or apply the change request. Once applied, the changes will be live in production.
-
-### Scheduled changes
+### Schedule a change
 
 :::note Availability
 
@@ -76,11 +65,11 @@ When a change request is approved, you can schedule it to be applied at a later
 
 Scheduled changes can be rescheduled, applied immediately, or rejected. They can not be edited or moved back to any of the previous states.
 
-When a scheduled change request is applied, the person who scheduled it and the person who created it will each receive a notification.
+When a scheduled change request is applied, the person who scheduled it and the person who created it each receive a notification.
 
 #### Conflicts
 
-If a change request contains changes that affect a flag that has been archived or a strategy that has been deleted, the change request can not be applied. Unleash will warn you ahead of time if you make changes that conflict with a scheduled change request.
+If a change request contains changes that affect a flag that has been archived or a strategy that has been deleted, the change request can not be applied. Unleash warns you ahead of time if you make changes that conflict with a scheduled change request.
 
 Further, if a strategy, project segment, or [environment-level variant](feature-toggle-variants) configuration that is updated in a scheduled change request is updated before the scheduled application time (for instance by a different change request being applied or by updates that circumvent the change request flow), Unleash will suspend the scheduled change request.
 
@@ -115,19 +104,7 @@ The second method uses Unleash's [constraints](strategy-constraints) and the [DA
 
 Another important distinction is how these changes affect your connected SDKs. If you use constraints (or segments), then any connected SDK will be aware of the schedule ahead of time. That means that even if the SDK can not connect to Unleash at the scheduled time, it will still activate the changes because it's encoded in its constraints. On the other hand, if you use change requests to schedule changes, SDKs **must** update their configuration after the scheduled time to be aware of the changes.
 
-## Change request permissions
-
-Change requests have their own set of environment-specific permissions that can be applied to [custom project roles](rbac#custom-project-roles). These permissions let users
-
-- approve/reject change requests
-- apply change requests
-- skip the change request flow
-
-None of the predefined roles have any change request permissions, so you must create your own project roles to take advantage of change requests. In other words, even a user with the project "owner" role can not approve or apply change requests.
-
-There is no permission to create change requests: **Anyone can create change requests**, even Unleash users with the [root viewer role](rbac#predefined-roles). Change requests don't cause any changes until approved and applied by someone with the correct permissions.
 
-You can prevent non-project members from submitting change requests by setting a [protected project collaboration mode](project-collaboration-mode).
 
 ### Circumventing change requests