Improve guide clarity and conciseness

guides/content-types.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Content types"
 description: "Choose the right content type for your documentation goals."
 keywords: ["Diátaxis", "tutorials", "how-tos", "reference", "explanation", "categorization"]
 ---
 
@@ -8,11 +8,11 @@
   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. 
 
 ## 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:
 
 1. Tutorials: Learning-oriented content for new users
 2. How-to guides: Task-oriented guidance for specific problems
@@ -38,17 +38,17 @@
 
 ## 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.
 
 ### How-To Guides (Problem-oriented)
 
 - **Audience goal**: Perform a specific task correctly.
 - **Characteristics**: Goal-driven and assumes some prior knowledge.
@@ -59,14 +59,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.
@@ -75,12 +75,12 @@
   - Acknowledge opinions and alternatives.
   - Draw connections to other areas in the product or industry.
 
-## Tips and tricks
+## Tips for success
 
-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.
+1. **Maintain purpose**: Before writing, assign each page a specific content type and stay focused on that purpose throughout.
+2. **Optimize for freshness**: Write evergreen documentation that remains accurate over time. Content tied to specific dates or frequently changing features belongs in changelogs or blog posts.
 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.
 

guides/improving-docs.mdx

@@ -10,13 +10,13 @@
 
 ## Quantitative metrics
 
-Some examples to consider:
+Track these metrics to understand documentation performance:
 
-- **Page views**: Views can be a good proxy for success, but could be driven by bot traffic or repeat visitors. If you're getting many views on an errors or explainer page, it might signal an issue with your broader product.
-- **Time on page**: Longer time on page might signal engagement, but could also mean users are stuck trying to find the information they need.
-- **Bounce rate**: A high bounce rate could mean users didn't find what they needed, or it could mean they found exactly what they needed and left satisfied.
+- **Page views**: High traffic indicates popular content, but context matters. Many views on error pages may signal product issues rather than documentation success.
+- **Time on page**: Can indicate engagement or confusion. Compare with user feedback to understand the difference.
+- **Bounce rate**: High bounce rates may mean users found answers quickly or couldn't find what they needed. Use qualitative feedback to interpret this metric accurately.
 
-The key is to compare these metrics over time or against a baseline to spot trends and understand if they align with users achieving their goals.
+Compare metrics over time against baselines to identify trends and understand whether users achieve their goals.
 
 ### Correlate traffic and satisfaction
 
@@ -39,7 +39,7 @@
 Measure documentation against broader business objectives:
 
 - **Support efficiency**: Track whether your documentation reduces the volume of support tickets or improves satisfaction scores, indicating it's meeting user needs.
 - **Onboarding and adoption**: Monitor how well documentation supports new users in getting up to speed, contributing to faster product adoption.
 - **Retention**: Well-maintained, easy-to-follow docs contribute to positive user experiences, helping to reduce churn and improve retention rates.
 
 ## Put analytics into action

guides/linking.mdx

@@ -4,11 +4,11 @@
 keywords: ["internal links", "cross-references", "anchor links", "broken links"]
 ---
 
-Effective linking creates a connected documentation experience that helps users discover related content and navigate efficiently. Too many links or broken links can confuse users and make your documentation less effective. This guide covers how to create and maintain links throughout your documentation.
+Effective linking creates a connected documentation experience that helps users discover related content and navigate efficiently. However, excessive or broken links confuse users and reduce documentation effectiveness. This guide covers creating and maintaining links throughout your documentation.
 
 ## Internal links
 
 Link to other pages in your documentation using root-relative paths. Root-relative paths start from the root of your documentation directory and work consistently regardless of where the linking page is located.
 
 ```mdx
 * [Quickstart guide](/quickstart)
@@ -46,7 +46,7 @@
 * [Customize your playground](/api-playground/overview#customize-your-playground)
 * [Cards properties](/components/cards#properties)
 
 ### How anchor links are generated
 
 Anchor links are automatically created from header text.
 
@@ -62,7 +62,7 @@
 | `#### Step 1: Install` | `#step-1-install` |
 
 <Note>
   Headers with the `noAnchor` prop will not generate anchor links. See [Format text](/create/text#disabling-anchor-links) for details.
 </Note>
 
 ## Link to API endpoints
@@ -86,7 +86,7 @@
 
 ### Write descriptive link text
 
 Use clear, descriptive text that indicates what users will find when they click.
 
 <CodeGroup>
 

guides/maintenance.mdx

@@ -8,31 +8,31 @@
   This page explains strategies for keeping your documentation accurate and valuable over time, from automated checks to content lifecycles.
 </Tip>
 
-## Automate what you can
+## Automate maintenance tasks
 
-Introduce automations where you can, such as:
+Reduce manual work with automation:
 
-- **Track stale content:** Run a script to flag important docs that haven't been updated in the last three months. Are they still accurate?
-- **Automate documentation updates:** Build a workflow to automatically update documentation when code is merged with the [agent API](/guides/automate-agent).
-- **Enforce standards with linters:** Use [Vale](http://Vale.sh) or [CI checks](/deploy/ci) to automatically catch formatting issues, writing style deviations, or missing metadata on every pull request.
+- **Track stale content**: Flag pages that haven't been updated in three months to verify accuracy.
+- **Automate updates**: Use the [agent API](/guides/automate-agent) to update documentation when code changes.
+- **Enforce standards**: Use [Vale](http://Vale.sh) or [CI checks](/deploy/ci) to catch formatting issues, style deviations, and missing metadata on every pull request.
 
-## Set up a review process
+## Establish review processes
 
-Documentation might never be perfect, and that's okay. You should have a threshold of acceptance where documentation is functional and useful. 
+Documentation doesn't need to be perfect. Set a quality threshold where content is functional and useful.
 
 Balance efficiency with quality:
 
-- **Focus on high-impact docs.** Not every page needs regular updates. Make sure the most important pages are reviewed regularly for accuracy and relevance.
-- **Leverage your community.** If your docs are open-source, empower users to flag issues or submit fixes via pull requests. This builds trust and keeps content fresh.
+- **Prioritize high-impact pages**: Focus regular reviews on the most important documentation. Not every page requires frequent updates.
+- **Leverage your community**: For open-source documentation, encourage users to flag issues or submit fixes. This builds trust and keeps content current.
 
-## Know when to rewrite
+## Recognize when to rewrite
 
-Over time, documentation naturally accumulates caveats and workarounds. When incremental fixes create more confusion than clarity, a full overhaul might be the best option.
+Documentation accumulates caveats and workarounds over time. When incremental fixes cause more confusion than clarity, consider a full rewrite.
 
-- **Plan for periodic resets.** A major cleanup, especially if best practices or the product itself has evolved significantly, saves time for your team and your users.
-- **Start with a structured audit.** Interview support teams, analyze user feedback, and document what is missing, misleading, or redundant before rewriting.
-- **Complete rewrites in focused sprints.** A full overhaul doesn't have to happen all at once. Prioritize sections with the biggest impact.
+- **Plan periodic overhauls**: Major cleanups save time when best practices or products evolve significantly.
+- **Audit before rewriting**: Interview support teams, analyze user feedback, and identify missing, misleading, or redundant content.
+- **Work in focused sprints**: Tackle rewrites in phases. Prioritize high-impact sections.
 
 ## Wrong docs can be worse than no docs
 
 Outdated or misleading documentation wastes users' time and erodes trust. In cases where a page is completely inaccurate and unfixable in the short term, it's often better to remove it entirely. Users will appreciate having less information over having wrong information.

guides/media.mdx

@@ -8,18 +8,18 @@ keywords: ["screenshots", "GIFs", "videos", "media best practices"]
   This page explains best practices for using screenshots, GIFs, and videos in your documentation.
 </Tip>
 
-Screenshots, GIFs, and videos can enhance documentation but require ongoing maintenance as UI elements change. Use them selectively to avoid unnecessary upkeep.
+Screenshots, GIFs, and videos enhance documentation but require maintenance as UI changes. Use them selectively to minimize upkeep.
 
 Key guidelines:
 
-- **Media should be supplementary.** If a workflow is clear in text alone, avoid adding visuals.
-- **Ensure accessibility.** Add alt text for images, subtitles for videos, and transcripts for audio content. Many people use assistive technology and accessible content benefits all users.
-- **Balance clarity with maintainability.** Frequent UI changes can make screenshots and videos outdated quickly. Consider whether the effort to update them is worth the value they add.
+- **Keep media supplementary**: If text explains a workflow clearly, skip visuals.
+- **Ensure accessibility**: Add alt text for images, subtitles for videos, and transcripts for audio. Accessible content benefits all users.
+- **Balance value with maintenance**: UI changes quickly outdate screenshots and videos. Consider whether update effort matches added value.
 
 ## When to use media
 
-* **Screenshots** for tasks that are difficult to explain with words.
-* **GIFs** for promotional purposes and short yet complex workflows.
-* **Videos** for abstract concepts and long workflows.
+- **Screenshots**: Tasks difficult to explain with words alone.
+- **GIFs**: Short complex workflows or promotional content.
+- **Videos**: Abstract concepts and lengthy workflows.
 
-Use media sparingly and intentionally to avoid unnecessary documentation debt. When done right, it enhances comprehension without adding maintenance burdens or accessibility barriers.
+Use media sparingly and intentionally. Effective media enhances comprehension without creating maintenance burdens or accessibility barriers.

guides/navigation.mdx

@@ -8,11 +8,9 @@
 This page explains why and how to organize your documentation in a way that makes sense for your users. 
 </Tip>
 
-## Why is navigation important?
+## Why navigation matters
 
-Navigation might seem unimportant because experienced users looking for specific answers typically navigate directly to pages via a search engine or your documentation site's search bar.
-
-But the information architecture of your documentation helps people build a mental model for how to think about your product, and provides structure for people and AI tools that use your documentation. Well designed navigation helps people quickly grasp your product and succeed when using your documentation.
+While experienced users often navigate directly to pages through search, navigation remains critical. Your documentation's information architecture helps users build mental models of your product and provides structure for people and AI tools. Well-designed navigation helps users quickly understand your product and find what they need.
 
 ## Map the foundation with stakeholders
 
@@ -26,7 +24,7 @@
 - How does the product's architecture influence how people use it?
 - What are the most important integrations or dependencies?
 - What is changing or evolving in the product?
 - If the product was broken into different layers, what would they be? Would it be by tasks that people perform or by features that people use?
 
 ## Validate your assumptions
 
@@ -53,13 +51,13 @@
 
 ## Identify common challenges
 
-Based on your observations, look for these common navigation problems:
+Look for these navigation problems:
 
-- **Overloaded categories:** Too many top-level sections can overwhelm users. Consider grouping related topics together.
-- **Hidden essential content:** Don't bury critical information. Prioritize frequently accessed content.
-- **Unclear section names:** If users hesitate before clicking, your labels might not be intuitive. Align terminology with how your audience naturally thinks.
+- **Overloaded categories:** Too many top-level sections overwhelm users. Group related topics together.
+- **Hidden essential content:** Prioritize frequently accessed content and make it easy to find.
+- **Unclear section names:** If users hesitate before clicking, your labels may not be intuitive. Align terminology with how your audience thinks.
 
-Try to design an elegant and functional information architecture, but remember, it's hard to make documentation that works for absolutely everyone. Consider the majority of your users and what will help them succeed.
+Design navigation that serves the majority of your users. Perfect information architecture for everyone is impossible, so focus on what helps most users succeed.
 
 ## Iterate over time
 

guides/seo.mdx

@@ -8,23 +8,21 @@
 This page explains fundamental strategies to optimize your documentation SEO.
 </Tip>
 
-## Content basics
+## Content fundamentals
 
-Make your writing and structure easy for search engines to scan.
+Structure content for search engines and readers:
 
-- **Headings and subheadings:** Use sequential, meaningful headers to structure your content. Each page has an H1 created from the `title:` property in the frontmatter.
-- **Short paragraphs and bullet points:** Break down large chunks of text into easily readable sections. Use bullet points and numbered lists where appropriate.
-- **Internal linking:** Link to related content using descriptive anchor text. For example, "Learn more about rate limiting" instead of "Click here."
+- **Headings and subheadings**: Use sequential, meaningful headers. Each page has an H1 from the `title:` property in frontmatter.
+- **Short paragraphs and lists**: Break large text blocks into readable sections. Use bullet points and numbered lists.
+- **Internal linking**: Link to related content with descriptive anchor text. Write "Learn more about rate limiting" instead of "Click here."
 
-## Technical SEO basics
+## Technical SEO essentials
 
-Once your content is optimized, ensure your documentation performs well from a technical standpoint. 
+Optimize technical elements for better discoverability:
 
-These basic technical SEO practices help make your docs more discoverable:
-
-- **Meta tags and descriptions:** Craft SEO-friendly titles (50-60 characters) and descriptions (150-160 characters) for each page. Most [meta tags](/optimize/seo) are automatically generated.
-- **Alt text for images:** Provide descriptive alt text for images with relevant keywords. For example, "OAuth 2.0 API authentication flow" instead of just "diagram". This enhances SEO and accessibility.
-- **Sitemaps:** Ensure your sitemap is up-to-date. Mintlify automatically generates a sitemap. However, you can manually create a sitemap if you prefer a custom format. Once created, search engines index site maps over time, but you can submit your sitemap directly to Google Search Console to speed up the process.
+- **Meta tags and descriptions**: Write SEO-friendly titles (50-60 characters) and descriptions (150-160 characters). Most [meta tags](/optimize/seo) are automatically generated.
+- **Alt text for images**: Include descriptive alt text with relevant keywords. Write "OAuth 2.0 API authentication flow" instead of "diagram" to improve SEO and accessibility.
+- **Sitemaps**: Mintlify automatically generates sitemaps. Submit your sitemap to Google Search Console to accelerate indexing.
 
 ## Page performance
 
@@ -32,12 +30,12 @@
 
 Examples of more advanced optimizations: 
 
 - **Optimize media for speed:** Compress images using formats like WebP or AVIF and ensure your pages load quickly (ideally under 3 seconds).
 - **Structured data (schema markup):** Add schema markup (like HowTo, FAQ) to your pages to help search engines better understand and rank your content.
 
 ## Keyword research
 
-To increase organic traffic, invest time into understanding which keywords help users land on your documentation.
+Understand which keywords drive users to your documentation:
 
-- **Keyword research:** Use free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases or long-tail keywords.
-- **Integrate keywords naturally:** Add keywords naturally into headings, subheadings, and throughout the body text. Don't overstuff keywords. Your documentation should be written for your users, not search engines.
+- **Research keywords**: Use tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases and long-tail keywords.
+- **Integrate naturally**: Add keywords to headings, subheadings, and body text where they fit naturally. Avoid keyword stuffing. Write for users, not search engines.

guides/style-and-tone.mdx

@@ -10,18 +10,18 @@
 
 ## 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.
-- **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.
-
-## Common writing mistakes
-
-- **Spelling and grammar mistakes.** Even a few spelling and grammar mistakes in your documentation make it less credible and harder to read.
-- **Inconsistent terminology.** Calling something an “API key” in one paragraph then “API token” in the next makes it difficult for users to follow along.
-- **Product-centric terminology.** Your users don't have the full context of your product. Use language that your users are familiar with.
-- **Colloquialisms.** Especially for localization, colloquialisms hurt clarity.
+- **Be concise**: Users read documentation to achieve goals. Get to the point quickly.
+- **Prioritize clarity**: Use simple, direct language. Avoid jargon and complex sentences.
+- **Use active voice**: Write "Create a configuration file" instead of "A configuration file should be created."
+- **Make content skimmable**: Use clear headings, short paragraphs, and bullet points for easy scanning.
+- **Write in second person**: Address readers as "you" to make instructions easier to follow and more personal.
+
+## Common mistakes to avoid
+
+- **Spelling and grammar errors**: Even minor mistakes reduce credibility and readability.
+- **Inconsistent terminology**: Switching between "API key" and "API token" confuses users. Use consistent terms throughout.
+- **Product-centric language**: Users lack internal context. Use familiar language that aligns with how they think.
+- **Colloquialisms**: Avoid informal expressions, especially in documentation intended for localization. They reduce clarity.
 
 ## Tips for enforcing style
 
@@ -37,7 +37,7 @@
 
 <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.