Merge pull request #6809 from harness/SEI-6919

feat: [SEI-6919]: Migrate prop-docs to Harness Developer Hub

docs/software-engineering-insights/early-access/metrics-reports/sei-business-alignment-report.md

@@ -15,7 +15,7 @@ The Business Alignment report feature is currently in BETA. Contact [Harness Sup
 
 <br />
 
-The report shows the effort invested for each category as a percentage, along with a label (`Ideal`, `Poor`, `Acceptable`) on the **Pie Chart**. The Trend Section displays the breakdown of the score over time in a **Stacked Bar Chart** format, based on the defined  Categories and their associated Allocation Goals in the [Business Alignment Profile](/docs/software-engineering-insights/early-access/profiles/sei-business-alignment-profile). The Bar Chart breaks down the metric value into time intervals as configured under the widget settings.
+The report displays the effort invested for each category as a percentage, along with a label (`Ideal`, `Poor`, `Acceptable`) on the **Pie Chart**. The Trend Section displays the breakdown of the score over time in a **Stacked Bar Chart** format, based on the defined  Categories and their associated Allocation Goals in the [Business Alignment Profile](/docs/software-engineering-insights/early-access/profiles/sei-business-alignment-profile). The Bar Chart breaks down the metric value into time intervals as configured under the widget settings.
 
 ![](./static/ba-report.png)
 
@@ -50,6 +50,53 @@ The data is represented in tabular format. Both the drill-down options support s
 Please note that the **Drilldown by Contributor** option is available only if the widget is configured to calculate effort by engineer (FTE).
 :::
 
+## Add the report
+
+### Step 1: Add the widget
+
+* Go to the Insight where you want to add the widget. Make sure you are in the correct project.
+
+* Select **Settings**, and then select **Add Widget**.
+
+* Select the **Business Alignment Report** widget.
+
+### Step 2: Configure the Filters on the widget
+
+* Define the **Issue Resolved In** filter as either in `relative` or `absolute` time frame. You can also enable the **Use Insight Time** option to consider the data as per the active date configured on the Insight.
+
+* You can add more conditions to specify what data feeds into the widget by creating inclusive and exclusive filters (For example: Project etc)
+
+* If you include multiple filters, they are inherently combined with an `AND` operator.
+
+### Step 3: Configure the widget settings
+
+* Select the **Business Alignment Profile** that you want to use in the metric calculation for the widget.
+
+* Select the **Effort Attribution** as either **Only use current assignee** or **Use current and previous assignee**
+  * **Only use current assignee:** This option considers only the current assignee of a ticket when calculating effort.
+  * **Use current and previous assignee:** This option considers both the current and previous assignees of a ticket when calculating effort.
+
+* Select the **Effort Unit** as either **Ticket count**, **Story points** or **Ticket time spent**. This essentially defines how you want to calculate the effort for your alignment metric calculations.
+  * **Ticket count:** The effort is calculated based on the number of tickets worked on.
+  * **Story points:** The effort is calculated based on the sum of story points assigned to the tickets.
+  * **Ticket time spent:** The effort is calculated based on the amount of time spent on tickets while they were in the **In Progress** status category.
+
+* Select the **Effort Calculation** as either **Absolute (By ticket)** or **FTE (By engineer)**. 
+  * **Absolute (By Ticket):** This considers the total number of tickets assigned within a specific category.
+  * **FTE (By Engineer):** This option considers the relative effort invested by the engineer across all the tickets that belong to different categories.
+
+:::info
+
+If the engineer has worked on 5 tickets, belonging to 3 different categories, their effort is distributed across the 3 categories based on the Effort Unit and Effort Attribution selected.
+
+:::
+
+* Select the interval for the widget to display the data. This option allows you to choose the time interval for which the widget should display the data, such as **Weekly**, **Bi-weekly**, **Monthly** or **Quarterly**.
+
+### Step 4: Save the widget
+
+Complete the widget settings and select **Next: Place Widget**, place the widget on Insight and then select **Save Layout**.
+
 ## Calculation Example
 
 In this example, we have a User X who is part of a team responsible for completing tasks in two different categories: Category A and Category B. These categories represent different types of work or projects within the team's scope.

docs/software-engineering-insights/early-access/metrics-reports/sei-lead-time-beta.md

@@ -0,0 +1,123 @@
+---
+title: Lead Time Improved Calculation
+description: A new calculation logic for computing the Lead Time metric.
+sidebar_position: 100
+sidebar_label: Lead Time Improved Calculation
+---
+:::info
+Note that the **202404.1.1 Release** introduced a new calculation logic for computing the **Lead Time** metric.
+:::
+
+Lead Time is a metric that measures the total time taken for an issue (e.g., a new feature, bug fix, or any other code change) to move through the entire software delivery pipeline, from the initial creation of the issue to its final release into production.
+
+The new calculation logic uses the time of the entry into each stage, rather than the exit time from that stage. This means that the **Lead Time** for a particular stage is calculated as the time taken for the issue to reach that stage for the first time, rather than the time spent in that stage itself.
+
+The **Lead Time** for a stage is calculated as the time difference between the start time of the current stage and the start time of the previous stage.
+
+```bash
+Lead Time for a Stage = Start Time of the Current Stage - Start Time of the Previous Stage
+```
+
+```bash
+Total Lead Time = Sum of the Lead Time of all the Individual Stages
+```
+
+The **Total Lead Time** is calculated by summing the **Lead Time** of all the individual stages.
+
+This change impacts the following reports:
+
+* **Issue Lead Time By Stage report**
+* **Issue Lead Time By Type report**
+* **SCM PR Lead Time by Stage report**
+* **DORA Lead Time for Changes report**.
+
+This feature is currently in **BETA** and is behind a Feature Flag. Contact [Harness Support](mailto:support@harness.io) to enable this feature.
+
+### **Calculation Example**
+
+In this example, we consider a use case where a single pull request (PR) is associated with a single Jira ticket. The new **Lead Time** calculation with stages for Issue Management, CI/CD Platform and SCM is displayed below.
+
+The table provides details on the different stages, their descriptions, formulas, and an example calculation.
+
+<table>
+  <thead>
+    <tr>
+      <th>Stage</th>
+      <th width="224">Description</th>
+      <th>Formula</th>
+      <th>Example</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Ticket In Progress Time</td>
+      <td>The time taken for a ticket to move from the <code>Created</code> state to the <code>In Progress</code> state for the first time.</td>
+      <td><code>In Progress Time - Ticket Created Time</code></td>
+      <td>10:00 AM - 9:50 AM = 10 minutes</td>
+    </tr>
+    <tr>
+      <td>First Commit Time</td>
+      <td>The time taken to make the first commit after the ticket is in progress.</td>
+      <td><code>First Commit Time - First In Progress Time</code></td>
+      <td>10:05 AM - 10:00 AM = 5 minutes</td>
+    </tr>
+    <tr>
+      <td>First Pull Request Creation Time</td>
+      <td>The time when the first pull request (PR) was created after the first commit.</td>
+      <td><code>First PR Creation Time - First Commit Time</code></td>
+      <td>10:10 AM - 10:05 AM = 5 minutes</td>
+    </tr>
+    <tr>
+      <td>First Pull Request Approval Time</td>
+      <td>The time taken for the first approval after the first pull request was created.</td>
+      <td><code>First PR Approval Time - PR Creation Time</code></td>
+      <td>10:11 AM - 10:10 AM = 1 minute</td>
+    </tr>
+    <tr>
+      <td>Last Pull Request Merge Time</td>
+      <td>The time taken to merge the pull request after it was approved.</td>
+      <td><code>Last PR Merged Time - First PR Approval Time</code></td>
+      <td>10:15 AM - 10:11 AM = 4 minutes</td>
+    </tr>
+    <tr>
+      <td>First Continuous Integration Time</td>
+      <td>The time taken to complete the continuous integration (CI) pipelines for the first time after the last pull request is merged.</td>
+      <td><code>CI Completion Time for First Time - Last PR Merged Time</code></td>
+      <td>10:16 AM - 10:15 AM = 1 minute</td>
+    </tr>
+    <tr>
+      <td>First Continuous Deployment Time</td>
+      <td>The time taken for the continuous deployment (CD) pipelines to complete for the first time after the CI process is finished.</td>
+      <td><code>CD Completion Time for First Time - CI Completion Time for First Time</code></td>
+      <td>10:17 AM - 10:16 AM = 1 minute</td>
+    </tr>
+    <tr>
+      <td>First Issue Management Done Time</td>
+      <td>The time taken to mark the issue as <code>Done</code> in the Issue Management System (e.g., Jira) after the CD process is completed.</td>
+      <td><code>Time at which the JIRA was marked as Done status for the First Time - CD Completion Time for First Time</code></td>
+      <td>10:20 AM - 10:17 AM = 3 minutes</td>
+    </tr>
+    <tr>
+      <td>First Release Time</td>
+      <td>The time at which the <code>fix version</code> added to the issue is released in Jira after the issue was marked as <code>Done</code> for the first time.</td>
+      <td><code>Jira Release Time - Time at which the JIRA was marked as Done status for the First Time</code></td>
+      <td>11:00 AM - 10:20 AM = 40 minutes</td>
+    </tr>
+  </tbody>
+</table>
+
+**Total Lead Time**
+
+The **Total Lead Time** is calculated by summing the time differences between consecutive stages:
+
+Substituting the example values, we get:
+
+```bash
+Total Lead Time = 10 min + 5 min + 5 min + 1 min + 4 min + 1 min + 1 min + 3 min + 40 min = 70 minutes
+```
+
+Therefore, the Total Lead Time for this example is **70 minutes**.
+
+:::info
+Note that for the **Lead Time** calculation, if an issue moves to the same status multiple times during its lifecycle, only the first transition to that status is used for calculating the Lead Time for that particular stage.
+:::

docs/software-engineering-insights/insights/developer-insight.md

@@ -170,7 +170,7 @@ To add the **SCM Commits Single Stat Report** widget to Insights:
 Similarly you can also configure the other Single Stat reports.
 Some other SCM related reports which are frequently used are
 
-* [SCM Rework Report](/docs/software-engineering-insights/sei-technical-reference/scm-metrics-calculation/scm-rework): The Rework report measures the refactoring of code, which involves making modifications to the existing codebase or rewriting it entirely.
+* [SCM Rework Report](/docs/software-engineering-insights/sei-technical-reference/scm-calculation/scm-reports-calculation/scm-rework-report ): The Rework report measures the refactoring of code, which involves making modifications to the existing codebase or rewriting it entirely.
 * [SCM Committers Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/scm-reports#scm-committers-report): This report analyzes the volume of code changes by committer.
 * [SCM Issues Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/scm-reports#scm-issues-reports): This report analyzes the number of issues in your SCM tool by time, label, or other categories.
 * [SCM Issues Count Single Stat](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/scm-reports#scm-issues-reports): This report displays a single stat related to the number of issues in your SCM tool.

docs/software-engineering-insights/insights/sei-insights.md

@@ -164,7 +164,7 @@ If you want to create a DORA Metrics Insight refer to the below resoures.
 
 Dev Insights examines development efforts, particularly in relation to SCM metrics, such as PR creation, merging, and review collaboration.
 
-For more information about SCM metrics and reports, go to [velocity metrics](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/velocity-metrics) and [SCM reports](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/scm-reports).
+For more information about SCM metrics and reports, go to [velocity metrics](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/velocity-metrics-overview) and [SCM reports](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/scm-reports).
 
 If you want to create a Developer i.e. SCM Metrics Insight refer to the below resources.
 
@@ -181,26 +181,26 @@ The Business Alignment Insight can help visualize where your teams expend the mo
 * **Effort Investment Trend Report**
 * **Effort Investment By Engineer**
 
-For more information about these reports and metrics, go to [effort investment metrics](/docs/software-engineering-insights/sei-metrics-and-reports/alignment-metrics-reports/effort-investment-metrics).
+For more information about these reports and metrics, go to [effort investment metrics](/docs/software-engineering-insights/sei-metrics-and-reports/planning/alignment/sei-business-alignment-overview).
 
 If you want to create additional Business Alignment Insights, select the **Effort Investment Profile** option under **Parameters** when [creating Insights](#create-insights).
 
 <!-- image /.gitbook/assets/image (4).png - Create dashboard with Effort Investment Profile selected -->
 
 ### Trellis
 
-Use the Trellis Insight to examine [Trellis Scores](/docs/software-engineering-insights/sei-metrics-and-reports/trellis-score).
+Use the Trellis Insight to examine [Trellis Scores](/docs/category/trellis-scores).
 
 If you want to create a Trellis Insight refer to the below resources.
 
 * [Tutorial: Create a Trellis Metrics Insight](/docs/software-engineering-insights/insights/trellis-insight)
-* [Trellis Reports](/docs/software-engineering-insights/sei-metrics-and-reports/trellis-score)
+* [Trellis Reports](/docs/category/trellis-scores)
 
 ### Planning Insights
 
-Use the Planning Insight to examine [sprint metrics](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics).
+Use the Planning Insight to examine [sprint metrics](/docs/category/sprint-metrics).
 
 If you want to create a Sprints Metrics Insight refer to the below resources.
 
 * [Tutorial: Create a Sprint Metrics Insight](/docs/software-engineering-insights/insights/sprint-metrics-insight)
-* [Sprint Metric Reports](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics)
+* [Sprint Metric Reports](/docs/category/sprint-metrics)

docs/software-engineering-insights/insights/sprint-metrics-insight.md

@@ -79,9 +79,9 @@ Use these sprint metric reports to analyze sprint and planning metrics allowing
 
 Engineering managers usually use these three key sprint metrics to get a holistic picture of the sprint productiviy:
 
-1. [Commit Points](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics#commit-points) (The number of story points you plan to complete during the sprint)
-2. [Commit Done Points](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics#commit-done-points) (The number of story points actually finished at the end of the sprint)
-3. [Creep Points](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics#creep-points) (The difference between the initially planned story points and those actually delivered).
+1. [Commit Points](/docs/category/sprint-metrics#commit-points) (The number of story points you plan to complete during the sprint)
+2. [Commit Done Points](/docs/category/sprint-metrics#commit-done-points) (The number of story points actually finished at the end of the sprint)
+3. [Creep Points](/docs/category/sprint-metrics#creep-points) (The difference between the initially planned story points and those actually delivered).
 
 The **Sprint Metrics Trend Report** is recommended for visualizing a time series trend of these metrics to help engineering managers understand how the respective sprint metrics has evolved throughout various sprint cycles.
 
@@ -102,7 +102,7 @@ To add the **Sprint Metrics Trend Report** widget to Insights:
    3. **Issue Management System:** Select the integration for your Issue Management System.
 9. Select **Next: Place Widget**, place the widget on the Insight, and then save the layout.
 
-For more information,go to [Sprint Metric Trend Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics).
+For more information,go to [Sprint Metric Trend Report](/docs/category/sprint-metrics).
 
 ### Issue Hygiene Report
 
@@ -195,7 +195,7 @@ To add the **Sprint Metrics Single Stat Report** widget to Insights:
 
 ### Other sprint metrics reports
 
-* [Sprit Metrics Percentage Trend Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics#sprint-metrics-percentage-trend-report)
-* [Sprint Impact of Unestimated Tickets Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics)
-* [Sprint Goal Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics)
-* [Sprint Distribution Retrospective Report](/docs/software-engineering-insights/sei-metrics-and-reports/velocity-metrics-reports/planning-sprint-metrics)
+* [Sprit Metrics Percentage Trend Report](/docs/category/sprint-metrics#sprint-metrics-percentage-trend-report)
+* [Sprint Impact of Unestimated Tickets Report](/docs/category/sprint-metrics)
+* [Sprint Goal Report](/docs/category/sprint-metrics)
+* [Sprint Distribution Retrospective Report](/docs/category/sprint-metrics)