docs - revise embedding docs (#27375)

* explanation and connective tissue

* heading promotion

* formatting

* note on full-app embedding

* hyphen

docs/embedding/full-app-embedding.md

@@ -8,13 +8,17 @@ redirect_from:
 
 {% include plans-blockquote.html feature="Full-app embedding" %}
 
-Metabase offers several [types of embedding](./introduction.md) with different levels of customization and security.
+**Full-app embedding** is what you want if you want to offer [multi-tenant, self-service analytics](https://www.metabase.com/learn/customer-facing-analytics/multi-tenant-self-service-analytics). 
 
-**Full-app embedding** is the only type of embedding that integrates with your [permissions](../permissions/introduction.md) and [SSO](../people-and-groups/start.md#authentication) to give people the right level of access to [query](https://www.metabase.com/glossary/query_builder) and [drill-down](https://www.metabase.com/learn/questions/drill-through) into your data.
+Full-app embedding is the only type of embedding that integrates with your [permissions](../permissions/introduction.md) and [SSO](../people-and-groups/start.md#authentication) to give people the right level of access to [query](https://www.metabase.com/glossary/query_builder) and [drill-down](https://www.metabase.com/learn/questions/drill-through) into your data.
 
-If you only want to set up a fixed number of filters and drill-down views into your data (i.e., prevent people from creating their own [questions](https://www.metabase.com/glossary/question)), you might prefer [Signed embedding](./signed-embedding.md).
+## Full-app embedding demo
 
-## Prerequisites
+To get a feel for what you can do with full-app embedding, check out our [full-app embedding demo](https://www.metabase.com/embedding-demo). 
+
+To see the query builder in action, click on **Reports** > **+ New** > **Question**.
+
+## Prerequisites for full-app embedding
 
 1. Make sure you have a [license token](../paid-features/activating-the-enterprise-edition.md) for a [paid plan](https://store.metabase.com/checkout/login-details).
 2. Organize people into Metabase [groups](../people-and-groups/start.md).

docs/embedding/introduction.md

@@ -8,17 +8,31 @@ redirect_from:
 
 You can embed Metabase tables, charts, and dashboards—even Metabase's query builder—in your website or application.
 
-[Signed embedding](./signed-embedding.md) (also known as standalone embedding) and [full-app embedding](./full-app-embedding.md) are _secure_ ways to share your data with specific groups of people outside of your organization.
+## Different ways to embed
 
-If you'd like to share your data with the good people of the internet, you can create a [public link](../questions/sharing/public-links.md) and embed that directly on your website.
+There are three ways to embed Metabase in your app:
 
-## How embedding works
+- [Full-app embedding](#full-app-embedding)
+- [Signed embedding](#signed-embedding)
+- [Public links and embeds](#public-links-and-embeds)
 
-You'll need to put an iframe on your website to act as a window to your Metabase app. Different configurations of that embedded iframe will let you:
+## Full-app embedding
 
-- [set up public access](../questions/sharing/public-links.md) to charts and dashboards,
-- [require sign-in](./signed-embedding.md) to view personalized versions of those charts and dashboards, or
-- [integrate with SSO and data permissions](./full-app-embedding.md) to enable self-service access to the underlying data.
+Full-app embedding is the only kind of embedding that [integrates with SSO and data permissions](./full-app-embedding.md) to enable true self-service access to the underlying data.
+
+**When to use full-app embedding**: when you want to [offer multi-tenant, self-service analytics](https://www.metabase.com/blog/why-full-app-embedding). With full-app embedding, people can create their own questions, dashboards, models, and more, all in their own data sandbox.
+
+## Signed embedding
+
+Also known as standalone embedding, signed embedding is a secure way to embed charts and dashboards.
+
+**When to use signed embedding**: you don’t want to give people ad hoc query access to their data for whatever reason, or you want to present data that applies to all of your tenants at once. For example, say you want to showcase some benchmarking stats: if you just want to make those stats available exclusively to your customers, you could use a signed embed.
+
+## Public links and embeds
+
+If you'd like to share your data with the good people of the internet, you can create a [public link](../questions/sharing/public-links.md) or embed a question or dashboard directly in your website.
+
+**When to use public links and embeds**: public links and embeds are good for one-off charts and dashboards. Use them when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don't care who sees the data; you want to make those stats available to everyone.
 
 ## Comparison of embedding types
 

docs/embedding/start.md

@@ -8,10 +8,15 @@ title: Embedding overview
 
 What is embedding, and how does it work?
 
+## [Full-app embedding](./full-app-embedding.md)
+
+The solution to self-service customer analytics: embed the full Metabase app in your app. Full-app embedding integrates with your data permissions to let people slice and dice data on their own using Metabase's query builder.
+
 ## [Signed embedding](./signed-embedding.md)
 
 Also known as Standalone Embedding, Signed Embedding offers drill-through with custom destinations, so you can define what happens when people click on a chart, like sending people to another chart or URL–all while securing the underlying data.
 
-## [Full-app embedding](./full-app-embedding.md)
+## [Parameters for signed embeds](./signed-embedding-parameters.md)
+
+You can pass parameters between Metabase and your website via the embedding URL to specify how Metabase items should look and behave inside the iframe on your website.
 
-Put all of Metabase in your app to give people secure self-serve access to data. You can still create custom destinations if you want, but Full-app Embedding integrates with your data permissions to let people slice and dice data on their own using Metabase's query builder.