mintlify · mintlify · Feb 3, 2026 · Feb 3, 2026 · Feb 3, 2026 · Feb 3, 2026
diff --git a/agent/index.mdx b/agent/index.mdx
@@ -8,7 +8,7 @@
   The agent is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent) for anyone with access to your dashboard.
 </Info>
 
-The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema.
+The agent creates pull requests with proposed documentation changes. It references your docs, repositories, and Slack messages to create content following technical writing best practices and the Mintlify schema.
 
 ## What you can do with the agent
 
@@ -22,7 +22,7 @@

 ## Where you can use the agent

 - **Dashboard**: From any page in your dashboard, use the keyboard shortcut <kbd>⌘</kbd>+<kbd>I</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>I</kbd> (Windows/Linux) to open the agent panel. Or click **Ask agent** on the [Overview](https://dashboard.mintlify.com/) page.
  <Frame>
    <img src="/images/agent/dashboard-light.png" alt="The agent panel open in the dashboard." className="block dark:hidden" />
    <img src="/images/agent/dashboard-dark.png" alt="The agent panel open in the dashboard." className="hidden dark:block" />

diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
@@ -6,7 +6,7 @@
 
 ## Overview
 
-The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation.
+The API playground lets users test and explore endpoints. Craft requests, submit them, and view responses without leaving your documentation.
 
 See [Trigger an update](/api/update/trigger) for an example of the API playground in action.
 
@@ -15,9 +15,9 @@
   <img src="/images/playground/API-playground-dark.png" alt="API playground for the trigger an update endpoint." className="hidden dark:block" />
 </Frame>
 
-The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages.
+The playground generates interactive pages from your OpenAPI or AsyncAPI spec. Updates automatically when you modify your API.
 
-We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
+Generate from an OpenAPI spec (recommended) or manually create pages after defining base URL and auth in `docs.json`.
 
 ## Get started
 
@@ -35,11 +35,11 @@
 
   </Step>
   <Step title="Generate endpoint pages.">
-    Update your `docs.json` to reference your OpenAPI specification.
+    Update `docs.json` to reference your OpenAPI spec.
 
-    **To automatically generate pages for all endpoints in your OpenAPI specification**, add an `openapi` property to any navigation element.
+    **To generate pages for all endpoints**, add an `openapi` property to any navigation element.
 
-    This example generates a page for each endpoint specified in `openapi.json` and organizes the pages in the "API reference" group.
+    This generates a page for each endpoint in `openapi.json`.
 
     ```json Generate all endpoint pages
     "navigation": {
@@ -52,9 +52,7 @@
     }
     ```
 
-    **To generate pages for only specific endpoints**, list the endpoints in the `pages` property of the navigation element.
-
-    This example generates pages for only the `GET /users` and `POST /users` endpoints. To generate other endpoint pages, add additional endpoints to the `pages` array.
+    **To generate pages for specific endpoints**, list them in the `pages` property.
 
     ```json Generate specific endpoint pages
     "navigation": {
@@ -76,7 +74,7 @@
 
 ## Customize your playground
 
-Customize your API playground by defining the following properties in your `docs.json`.
+Define these properties in `docs.json`:
 
 <ResponseField name="playground" type="object">
     Configurations for the API playground.
@@ -118,7 +116,7 @@
 
 ### Example configuration
 
-This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets, and the playground prefills the request body with example values.
+Interactive playground with cURL, Python, and JavaScript snippets. Shows only required parameters and prefills request body with examples.
 
 ```json
 {
@@ -137,7 +135,7 @@
 
 ### Auth-based playground display
 
-Use the `auth` display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users.
+Show the playground only to authenticated users. Useful for public docs with restricted playground access.
 
 When `display` is set to `auth`:
 - Authenticated users see the interactive playground.
@@ -168,17 +166,11 @@
 
 ### Custom endpoint pages
 
-When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual MDX pages for your endpoints.
-
-Both options allow you to:
-
-- Customize page metadata
-- Add additional content like examples
-- Control playground behavior per page
+For more control, use the `x-mint` extension in your OpenAPI spec or create individual MDX pages.
 
-The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
+Both let you customize metadata, add content, and control playground behavior.
 
-Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.
+Use `x-mint` to maintain all API docs in one file (recommended). Use MDX pages for small APIs or per-page experimentation.
 
 ## Further reading
 

diff --git a/components/index.mdx b/components/index.mdx
@@ -5,7 +5,7 @@
   ["MDX components", "documentation components", "UI components", "components"]
 ---
 
-Mintlify provides built-in MDX components for your documentation pages. Use these components to structure content, draw attention to important information, document APIs, and guide navigation.
+Built-in MDX components for structuring content, highlighting information, documenting APIs, and guiding navigation.
 
 ## Structure your content
 
@@ -97,7 +97,7 @@
  Display content in a grid of clickable tiles.
 </Card>

 ## Add visual context

 <Card title="Icons" icon="smile" href="/components/icons">
  Add visual indicators using the Lucide icon library.

diff --git a/editor/index.mdx b/editor/index.mdx
@@ -17,7 +17,7 @@ keywords: ["editor", "visual", "gitbook"]
   alt="Decorative image in dark mode"
 />
 
-Create, edit, and publish documentation directly in your browser with the web editor. View and share previews of your changes; manage your site's navigation structure with drag-and-drop components; and publish updates using your team's preferred workflow.
+Create, edit, and publish documentation in your browser. View and share previews, manage navigation with drag-and-drop, and publish using your team's workflow.
 
 ## Key features
 

diff --git a/guides/content-types.mdx b/guides/content-types.mdx
@@ -1,25 +1,21 @@
 ---
 title: "Content types"
 description: "Choose the right content type for your documentation goals."
 keywords: ["Diátaxis", "tutorials", "how-tos", "reference", "explanation", "categorization"]
 ---
 
-<Tip>
-  This page explains different content types, when to use each one, and how to approach writing for each type.
-</Tip>
-
-Documentation should be organized around the specific goal you're trying to help people achieve. 
+Organize documentation around user goals. 
 
 ## Categorize using the Diátaxis framework
 
-The [Diátaxis framework](https://diataxis.fr) is a helpful guide for categorizing content based on your audience's needs. Documentation can generally be mapped into one of these types:
+The [Diátaxis framework](https://diataxis.fr) categorizes content by audience needs:
 
-1. Tutorials: Learning-oriented content for new users
-2. How-to guides: Task-oriented guidance for specific problems
-3. Explanations: Understanding-oriented conceptual discussions
-4. Reference: Information-oriented technical descriptions
+1. **Tutorials**: Learning-oriented for new users
+2. **How-to guides**: Task-oriented for specific problems
+3. **Explanations**: Understanding-oriented conceptual discussions
+4. **Reference**: Information-oriented technical descriptions
 
-Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need.
+Clear content types help users find what they need.
 
 <Frame>
 <img src="/images/guides/best-practices/diataxis.webp" alt="A diagram of the Diátaxis framework showing four quadrants that correspond to the four content types: Tutorials, How-To Guides, Reference, and Explanation." />
@@ -38,17 +34,13 @@

 ## Writing for each type
 
 ### Tutorials (Learning-oriented)
 
-- **Audience goal**: Learn something new through step-by-step instructions.
-- **Characteristics**: Sequential and assumes no prior knowledge.
-- **Writing approach**:
-  - Set expectations of what the user will achieve after reading.
-  - Use clear, incremental steps. Minimize choices that need to be made by the user.
-  - Point out milestones along the way.
-  - Minimize theory and focus on concrete actions.
+- **Goal**: Learn through step-by-step instructions
+- **Characteristics**: Sequential, assumes no prior knowledge
+- **Writing approach**: Set expectations, use clear incremental steps, minimize choices, point out milestones, focus on actions over theory
 
 ### How-To Guides (Problem-oriented)
 
 - **Audience goal**: Perform a specific task correctly.
 - **Characteristics**: Goal-driven and assumes some prior knowledge.
@@ -59,14 +51,14 @@

 ### Reference (Information-oriented)

 - **Audience goal**: Find details about a product's functionality.
 - **Characteristics**: Unambiguous, product-focused, scannable.
 - **Writing approach**:
  - Be scannable and concise.
  - Prioritize consistency.
  - Avoid explanatory content. Focus on examples that are easy to copy and modify.

 ### Explanation (Understanding-oriented)

 - **Audience goal**: Expand general understanding of a concept or highly complex feature.
 - **Characteristics**: Theoretical, potentially opinionated, broad in scope.
@@ -77,10 +69,10 @@

 ## Tips and tricks

 1. **Maintain purpose**: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing.
 2. **Consider content freshness**: Regardless of content type, try to optimize for evergreen documentation. If something represents a moment in time of what a feature looks like on a specific date, it's probably better suited for a changelog or blog post than in your documentation. Or if something changes very frequently avoid putting it in your docs.
 3. **Think like your users**: Consider different user personas when organizing content. See [Understand your audience](/guides/understand-your-audience) for more information.
 4. **Use templates**: Start with [content templates](/guides/content-templates) that provide the basic structure for each content type.

 While the Diátaxis framework provides a starting point, successful documentation requires contextual adaptation to your product. Start by understanding the framework's principles, then adjust them to serve your users' needs.


diff --git a/guides/index.mdx b/guides/index.mdx
@@ -3,9 +3,7 @@
 description: "Learn how to create effective documentation with best practices and workflows."
 ---
 
-The guides in this section contain advice for creating documentation that helps your users succeed. Whether you're starting from scratch or improving existing docs, these guides help you plan, write, and maintain your documentation.
-
-Above all else, consider your users' needs and goals. Document what helps them use your product and get back to their tasks.
+Advice for creating documentation that helps users succeed. Plan, write, and maintain docs that address user needs and goals.
 
 ## Topics
 
@@ -30,7 +28,7 @@

 - [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible.
 - [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations.
 - [Content templates](/guides/content-templates): Copy and modify templates for each content type.
 - [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation.
 - [Internationalization](/guides/internationalization): Set up multi-language documentation to reach global audiences.
 - [Linking](/guides/linking): Create internal links, reference API endpoints, and maintain link integrity across your documentation.

diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx
@@ -4,17 +4,15 @@
 keywords: ["writing principles", "active voice", "technical writing", "style guides"]
 ---
 
-<Tip>
-  This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation. 
-</Tip>
+
 
 ## Writing principles
 
-- **Be concise.** People are reading documentation to achieve a goal. Get to the point quickly.
-- **Clarity over cleverness.** Be simple, direct, and avoid jargon or complex sentence structure.
+- **Be concise.** Get to the point quickly.
+- **Clarity over cleverness.** Be simple and direct. Avoid jargon.
 - **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file."
-- **Be skimmable.** Use headlines to orient readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan.
-- **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal.
+- **Be skimmable.** Use headlines, break up paragraphs, use lists.
+- **Write in second person.** Address the reader directly.
 
 ## Common writing mistakes
 
@@ -25,19 +23,19 @@
 
 ## Tips for enforcing style
 
-Leverage existing style guides to standardize your documentation:
+Use existing style guides:
 
 - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
 - [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
 - [Google Developer Documentation Style Guide](https://developers.google.com/style)
 
-When you know which writing principles you want to implement, automate as much as you can. You can use  [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh).
+Automate with [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh).
 
 ## Related pages
 
 <CardGroup cols={2}>
  <Card title="Content types" icon="folder-tree" href="/guides/content-types">
    Choose the right content type for your documentation goals.
  </Card>
  <Card title="Accessibility" icon="person-standing" href="/guides/accessibility">
    Make your documentation accessible to more users.