Add an overview page about reports. (#367)

* Add an overview page about reports. Update the existing reporting pages a bit, to build a couple of user journeys. Reorder the pages in the ToC.

* Fix formatting.

* Typo fix.

Author: jmacdotorg

docs/guides/custom-reports.md

@@ -11,6 +11,8 @@ import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
 
 CodeRabbit Pro allows you to create custom reports tailored to your specific needs using a flexible prompt-based system. This guide will help you understand how to create effective custom reports.
 
+For a conceptual overview of reports in CodeRabbit, see [Generate reports](/guides/reports-overview).
+
 ## Understanding Custom Reports
 
 Custom reports allow you to:
@@ -558,6 +560,6 @@ These are the available emojis and the type of change they represent. Do not usi
 
 ## Related Resources
 
-- [Scheduled Reports](./scheduled-reports.md)
-- [On-demand Reports](./ondemand-reports.md)
+- [Schedule reports](/guides/scheduled-reports)
+- [Generate reports on demand](/guides/ondemand-reports)
 - [API Documentation](https://api.coderabbit.ai/api/swagger/)

docs/guides/ondemand-reports.md

@@ -1,5 +1,5 @@
 ---
-title: Generate reports
+title: Generate reports on demand
 description: CodeRabbit offers a way to generate on-demand reports using a simple API request
 ---
 
@@ -12,13 +12,9 @@ import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
 
 ## Overview
 
-CodeRabbit's reporting feature helps you track and analyze pull request activity across your repositories. There are two ways to generate reports:
+This page is about using the CodeRabbit API to generate on-demand reports about your organization's usage of CodeRabbit. For a conceptual overview of reports in CodeRabbit, see [Generate reports](/guides/reports-overview).
 
-1. **[Scheduled Reports](./scheduled-reports.md)** - Set up automated recurring reports that are delivered on a schedule to your preferred channels (email, Slack, MS Teams). This is the recommended way to keep your team informed about development progress.
-
-2. **On-demand Reports** (this guide) - Generate reports programmatically through our API when you need them. This is useful for integration with your own tools and workflows.
-
-If you're new to CodeRabbit's reporting features, we recommend starting with [Scheduled Reports](./scheduled-reports.md) to understand the available options and capabilities.
+If you're new to CodeRabbit's reporting features, then we recommend starting with [Scheduled reports](/guides/scheduled-reports) to understand the available options and capabilities.
 
 ## API Access
 
@@ -73,3 +69,8 @@ The on-demand report generation endpoints take in inputs as per the schema shown
 ```
 
 [API Reference](https://api.coderabbit.ai/api/swagger/)
+
+## What's next
+
+- [Customize reports](/guides/custom-reports)
+- [Scheduled reports](/guides/scheduled-reports)

docs/guides/reports-overview.md

@@ -0,0 +1,38 @@
+---
+title: Generate reports
+description: Learn about CodeRabbit's reporting capabilities, including scheduled and on-demand reports, and how to customize them
+sidebar_label: Overview
+---
+
+```mdx-code-block
+import ReportSchema from "@site/src/components/ReportSchema";
+import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
+
+<ProPlanNotice />
+```
+
+You can track and analyze pull request activity across your organization's repositories by using the CodeRabbit reporting feature.
+
+## Scheduled and on-demand reports {#types}
+
+There are two ways to generate reports:
+
+- **[Scheduled Reports](/guides/scheduled-reports)**: Set up automated, recurring reports that are delivered to your team on a set schedule. Supported delivery channels include the following:
+
+  - Email
+  - Discord
+  - Slack
+  - Teams
+
+- **[On-demand Reports](/guides/ondemand-reports)**: If you require customized integration of reports with your own tools and workflows, then you can generate reports programmatically through our API.
+
+For your first reports, we recommend exploring scheduled reports. Its web-based UI can help you get familiar with the options available to you.
+
+## Customize reports using natural language {#customize}
+
+For both scheduled and on-demand reports, you define the shape and content of your reports by providing a prompt that instructs CodeRabbit about report that you want, using natural language. The scheduled reports interface includes several example prompts that you can choose from, or you can write your own prompt. For more information, see [Customize reports](/guides/custom-reports).
+
+## What's next {#whats-next}
+
+- [Schedule reports](/guides/scheduled-reports)
+- [Generate reports on demand](/guides/ondemand-reports)

docs/guides/scheduled-reports.md

@@ -11,6 +11,8 @@ import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
 
 CodeRabbit Pro offers automated recurring reports that provide insights into your GitHub organization's activities. These reports can be customized and delivered through various channels to help teams stay informed about development progress.
 
+For a conceptual overview of reports in CodeRabbit, see [Generate reports](/guides/reports-overview).
+
 ## Setting Up a Recurring Report
 
 1. Navigate to **Recurring Reports** in the [CodeRabbit dashboard](https://app.coderabbit.ai/reports/recurring)
@@ -248,3 +250,8 @@ Deleting a report will immediately stop all scheduled runs and remove access to
 - [Custom Reports](./custom-reports.md)
 - [On-demand Reports](./ondemand-reports.md)
 - [API Documentation](https://api.coderabbit.ai/api/swagger/)
+
+## What's next
+
+- [Customize reports](/guides/custom-reports)
+- [Generate reports on demand](/guides/ondemand-reports)

sidebars.ts

@@ -129,9 +129,10 @@ const sidebars: SidebarsConfig = {
 			collapsed: true,
 			label: "Generate reports",
 			items: [
+				"guides/reports-overview",
+				"guides/scheduled-reports",
 				"guides/ondemand-reports",
 				"guides/custom-reports",
-				"guides/scheduled-reports",
 			],
 		},
 		{