GITBOOK-535: Add docs for Advanced Insights and AI Change Requests

Addison Schultz · gitbook-bot · commit eeb60a4a0d0d · 2025-02-03T04:09:00.000Z
diff --git a/.gitbook/assets/03_02_25_advanced_site_insights.svg b/.gitbook/assets/03_02_25_advanced_site_insights.svg
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -80,6 +80,7 @@
 
 * [Live edits](collaboration/live-edits.md)
 * [Change requests](collaboration/change-requests.md)
+* [AI change requests](collaboration/ai-change-requests.md)
 * [PDF export](collaboration/pdf-export.md)
 * [Inviting your team](collaboration/share.md)
 * [Comments](collaboration/comments.md)
diff --git a/account-management/cancelling-a-plan.md b/account-management/cancelling-a-plan.md
@@ -9,7 +9,11 @@ If you’re thinking about cancelling a plan because you’re running into any i
 
 Here’s how to cancel your plan:
 
-1. Go to the organization’s settings page. You can click on the settings <picture><source srcset="../.gitbook/assets/settings_icon_dark.svg" media="(prefers-color-scheme: dark)"><img src="../.gitbook/assets/settings_icon_light.svg" alt=""></picture> icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
+1.  Go to the organization’s settings page. You can click on the settings&#x20;
+
+    <picture><source srcset="../.gitbook/assets/settings_icon_dark.svg" media="(prefers-color-scheme: dark)"><img src="../.gitbook/assets/settings_icon_light.svg" alt=""></picture>
+
+    &#x20;icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
 2. Click on the **billing** tab. This will take you to a billing page hosted on Stripe, our payment processor.
 3. Click the **cancel plan** button.
 4. On the following page, confirm by clicking a second button labelled **cancel plan**.
diff --git a/collaboration/ai-change-requests.md b/collaboration/ai-change-requests.md
@@ -0,0 +1,48 @@
+---
+hidden: true
+icon: sparkles
+---
+
+# AI change requests
+
+### Overview
+
+The **AI Change Requests** feature brings the capabilities of GitBook AI to one of the core functionalities of GitBook: Change Requests. This feature streamlines the process of proposing, planning, and implementing changes to your GitBook content by leveraging AI assistance.
+
+With AI Change Requests, you can:
+
+* **Start a new Change Request**: Describe the modifications you want to make, and GitBook AI will draft a plan for review.
+* **Refine and approve the plan**: Review and adjust the AI-generated proposal as needed.
+* **Execute the changes**: Once finalized, GitBook AI will apply the changes directly to your content.
+
+### How It Works
+
+1. **Initiate a Change Request**
+   * Open GitBook and navigate to the Change Requests section.
+   * Start a new Change Request and describe the desired changes. Examples of requests include:
+     * "Find and replace any instances of \[feature name] with \[updated feature name]."
+     * "Correct typos on the Welcome page."
+     * "Reformat the \[product feature] page into three sections: Overview, Installation, and FAQ."
+     * "Add a new page for \[product feature] and document it based on this description: \[product description]."
+2. **Review and Tweak the AI-Generated Plan**
+   * GitBook AI will draft a proposed plan based on your description.
+   * You can review, edit, and refine the draft to ensure it aligns with your vision.
+3. **Execute the Plan**
+   * Approve the final plan to allow GitBook AI to apply the requested changes directly to your project.
+
+### Example Use Cases
+
+* **Content Updates**: Quickly update outdated terminology or features across multiple pages.
+* **Error Correction**: Automatically detect and fix typos or grammatical errors in your documentation.
+* **Page Reorganization**: Restructure content into clear and logical sections.
+* **New Content Creation**: Generate new pages or sections based on high-level descriptions.
+
+### Current Limitations
+
+While the AI Change Requests feature is still in Alpha, there are some known limitations:
+
+* **GitBook-specific blocks**: Updates to these blocks are not yet supported.
+
+### Feedback and Support
+
+As this feature is in its early stages, we welcome your feedback to improve its functionality. Please share your experiences and suggestions with the GitBook team to help us refine AI Change Requests.
diff --git a/creating-content/write-and-edit-with-ai.md b/creating-content/write-and-edit-with-ai.md
@@ -1,5 +1,5 @@
 ---
-icon: robot
+icon: wand-magic-sparkles
 description: Use GitBook AI to generate and build content for your page
 ---
 
diff --git a/getting-started/quickstart.md b/getting-started/quickstart.md
@@ -19,7 +19,7 @@ The docs site wizard will take you through the flow of creating your first site.
 
 ### Edit your content
 
-Now that you’ve created a site, you can edit or import your content. If you have an existing repository on GitHub or GitLab with your documentation, you can easily migrate and sync your content to GitBook using [Git Sync](git-sync/). Find out more in [our guide to migrating content using Git Sync](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/migrate-your-content-to-gitbook-with-git-sync).
+Now that you’ve created a site, you can edit or import your content. If you have an existing repository on GitHub or GitLab with your documentation, you can easily migrate and sync your content to GitBook using [Git Sync](git-sync/). Find out more in [our guide to migrating content using Git Sync](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/import-or-migrate-your-content-to-gitbook-with-git-sync).
 
 After importing your content, you can edit your pages using GitBook’s built-in editor and do things like [add interactive blocks](../creating-content/blocks/), customize the [layout of your pages](../creating-content/content-structure/page.md) and more.
 
@@ -46,5 +46,5 @@ After publishing your site, you’ll get a link that you’re able to share with
 If you’re running into problems or have any questions, we’re here to help. [Join our community](https://github.com/orgs/GitbookIO/discussions) or [send our support team a message](https://docs.gitbook.com/help-center/support/how-do-i-contact-support) and we’ll help you from there.
 
 {% hint style="success" %}
-Want to explore publishing in more details? Check out [our complete guide to creating and publishing content in GitBook](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/the-complete-guide-to-creating-and-publishing-documentation-in-gitbook-updated-for-2024).
+Want to explore publishing in more details? Check out [our complete guide to creating and publishing content in GitBook](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/complete-guide-to-publishing-docs-gitbook).
 {% endhint %}
diff --git a/publishing-documentation/insights.md b/publishing-documentation/insights.md
@@ -9,51 +9,57 @@ description: View analytics and insights related to your published documentation
 This feature is available on [Premium and Ultimate site plans](https://www.gitbook.com/pricing).
 {% endhint %}
 
-Insights give you information on the content you've published and how it performs. It's split up between three sections — **traffic**, **search** and **feedback**.
+Insights give you information on the content you've published and how it performs. It's split up between different sections — **traffic**, **pages & feedback**, **search**, **ask AI**, **links**, and **OpenAPI**.
 
-You can find insights for individual docs sites in the docs site dashboard, and can sort it by the last week, month and year.&#x20;
+You can find insights for individual docs sites in the docs site dashboard, and can sort it by the last day, week and month. You can download insights by hovering over the header for the data you want, and clicking **Download CSV**.
 
-<figure><img src="../.gitbook/assets/10_01_25_site_insights.svg" alt=""><figcaption><p>The site insights dashboard.</p></figcaption></figure>
+<figure><img src="../.gitbook/assets/03_02_25_advanced_site_insights.svg" alt=""><figcaption><p>The site insights dashboard.</p></figcaption></figure>
 
 ### Traffic
 
 GitBook tracks page views to help you understand the popularity and reach of your content. Each time a user visits a page on your docs site, it is counted as a page view.&#x20;
 
-This information is compiled and displayed in the Traffic section of the Insights tab, allowing you to identify which pages are most visited and engage the most readers. Page views are critical for assessing the effectiveness of your content strategy and optimizing your documentation based on user interest.
+Page views are critical for assessing the effectiveness of your content strategy and optimizing your documentation based on user interest. It’s split up between different views and profiles, including countries, languages, browsers, and more.
 
-### Search
+### Pages & Feedback
 
-You can measure and improve your documentation by checking which keywords are used the most by users searching your documentation.
+Pages & feedback allow you to see a high-level representation of how your users rate your content. You’ll see an overview of all of your site’s sections and variants, and after enabling [page rating](site-settings.md#page-ratings-pro-and-enterprise-plans) in the **Customize** menu for a site, you can see each page’s average feedback rating.
 
-Switch to the **Search analytics** tab to see what keywords are performing the best, and which ones you could improve on. You can view these search terms for the past week, month, or year.
+If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
 
-The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.
+You can also see a list of comments left from visitors who rate your pages, to get actionable insights on how your docs can be improved.
 
-If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
+#### How does GitBook calculate user scores?
+
+GitBook uses a simple formula to calculate the page’s overall score:
+
+`no. of ratings * (no. of positives - [0.5 * no. of neutrals] - [2 * no. of negatives])`
+
+The goal of the content score is to surface the pages with the most feedback, with a bias towards negative ratings so you can see pages that need improvements. The more ratings a page has, the more the formula amplifies the sentiments of those ratings. This helps you spot pages that need attention, as well as pages that are highly-rated — to help you identify, iterate on and replicate your best content.
 
-You’ll get information on:
+We cap the score at 500 (and -500) to avoid scores for commonly-rated pages reaching 10,000+.
 
-`pageHits`: Total number of pages (title and description) matching the search term/query .
+### Search
 
-`sectionHits`: Total number of sections (contents of the pages) matching the search term/query.
+You can measure and improve your documentation by checking which keywords are used the most by users searching your documentation. This view allows you to see what keywords are performing the best, and which ones you could improve on.&#x20;
 
-### Feedback
+The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.
 
-Content scores give you a high-level representation of how your users rate your content. After enabling [page rating](site-settings.md#page-ratings-pro-and-enterprise-plans) in the **Customize** menu for a site, you can see each page’s average feedback rating here.
+### Ask AI
 
-You’ll initially see the ratings for your site’s default content, and you can use the dropdown menu on the right to select any other linked spaces in that site. You can then hover over the average rating to see how many positive, neutral and negative ratings a specific page has.
+The [Ask AI](../creating-content/searching-your-content/gitbook-ai.md) section allows you to see what your users are asking for when using GitBook AI. This insight helps you identify common questions, uncover gaps in your documentation, and improve content to better meet user needs.&#x20;
 
-If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
+By looking at these queries, you can refine your documentation structure, enhance discoverability, and provide more relevant information to your audience.
 
-#### How does GitBook calculate user scores?
+### Links
 
-GitBook uses a simple formula to calculate the page’s overall score:
+GitBook tracks links to help you understand how users interact with external resources in your documentation. This feature provides insights into external links, their domains, and their placement within your docs, such as in the header, footer, or sidebar. Analyzing link usage can help you optimize navigation, improve content accessibility, and refine your documentation strategy based on user engagement.
 
-`no. of ratings * (no. of positives - [0.5 * no. of neutrals] - [2 * no. of negatives])`
+### OpenAPI
 
-The goal of the content score is to surface the pages with the most feedback, with a bias towards negative ratings so you can see pages that need improvements. The more ratings a page has, the more the formula amplifies the sentiments of those ratings. This helps you spot pages that need attention, as well as pages that are highly-rated — to help you identify, iterate on and replicate your best content.
+The [OpenAPI](../creating-content/openapi/) analytics view in GitBook provides insights into how users engage with your API documentation.&#x20;
 
-We cap the score at 500 (and -500) to avoid scores for commonly-rated pages reaching 10,000+.
+It tracks interactions such as endpoint views, parameter searches, and request explorations, helping you understand which parts of your API are most accessed and where users may need more clarity. These insights enable you to refine your documentation, improve developer experience, and ensure your API content is effectively meeting user needs.
 
 {% hint style="info" %}
 **Why can’t I see any data for my site?**\
