Try to unnest explanations

doc/explanation/api/index.md

@@ -12,11 +12,18 @@ Let's work through each API with an example app, while pointing out the benefits
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
+:::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Parameters in Panel
+:link: reactivity
+:link-type: doc
+
+Background on the use of Param in Panel.
+:::
+
 :::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Reactivity in Panel
 :link: reactivity
 :link-type: doc
 
-A discussion that contrasts reactive and callback based APIs in Panel.
+A deep dive into the reactive and callback based APIs in Panel.
 :::
 
 :::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Functions vs Classes
@@ -26,11 +33,18 @@ A discussion that contrasts reactive and callback based APIs in Panel.
 A discussion that contrasts function and class based APIs in Panel.
 :::
 
+::::
+
+Next let us contrast the different APIs offered by Panel by applying them to a particular problem.
+
+::::{grid} 1 1 3 3
+:gutter: 1 1 1 2
+
 :::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` 1. Reactive API
 :link: reactive
 :link-type: doc
 
-Linking functions or methods to widgets using ``pn.bind`` or the equivalent ``pn.depends`` decorator.
+Linking functions or methods to widgets using `pn.bind` or the equivalent `pn.depends` decorator.
 :::
 
 :::{grid-item-card} {octicon}`codespaces;2.5em;sd-mr-1 sd-animate-grow50` 2. Declarative API

doc/explanation/index.md

@@ -4,13 +4,13 @@ The explanation section aims to clarify, deepen, and broaden the understanding o
 
 Beyond the [Getting Started > Core Concepts](../getting_started/core_concepts.md), which new users must complete before working with Panel, this explanation section is intended to help practitioners form and strengthen a conceptual web that facilitates new and advanced usage directions.
 
-## Develop
+## Developing in Panel
 
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
 :::{grid-item-card} {octicon}`code;2.5em;sd-mr-1 sd-animate-grow50` Develop Seamlessly
-:link: api/index
+:link: develop_seamlessly
 :link-type: doc
 
 Learn how we enable you and your team to work seamlessly with Panel across a wide range of development environments
@@ -20,14 +20,96 @@ Learn how we enable you and your team to work seamlessly with Panel across a wid
 
 ## APIs
 
+In this section we will discuss the principles and design decisions behind Panel's APIs in order to guide you towards the best approach for structuring your applications. We begin with a set of explanations behind the use of Param in Panel, how it unlocks reactive approaches to write applications and contrast function and class based approaches for writing apps.
+
+::::{grid} 1 1 3 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Parameters in Panel
+:link: api/param
+:link-type: doc
+
+Background on the use of Param in Panel.
+:::
+
+:::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Reactivity in Panel
+:link: api/reactivity
+:link-type: doc
+
+A deep dive into the reactive and callback based APIs in Panel.
+:::
+
+:::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` Functions vs Classes
+:link: api/functions_vs_classes
+:link-type: doc
+
+A discussion that contrasts function and class based APIs in Panel.
+:::
+
+::::
+
+Next let us contrast the different APIs offered by Panel by applying them to a particular problem.
+
+::::{grid} 1 1 3 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`infinity;2.5em;sd-mr-1 sd-animate-grow50` 1. Reactive API
+:link: api/reactive
+:link-type: doc
+
+Linking functions or methods to widgets using `pn.bind` or the equivalent `pn.depends` decorator.
+:::
+
+:::{grid-item-card} {octicon}`codespaces;2.5em;sd-mr-1 sd-animate-grow50` 2. Declarative API
+:link: api/parameterized
+:link-type: doc
+
+Declare *Parameters* and their ranges in `Parameterized` classes, then get GUIs (and value checking!) for free.
+:::
+
+:::{grid-item-card} {octicon}`link;2.5em;sd-mr-1 sd-animate-grow50` 3. Callbacks API
+:link: api/callbacks
+:link-type: doc
+
+Generate a UI by manually declaring callbacks that update panels or panes.
+:::
+
+::::
+
+Finally let's look at some examples demonstrating how each API can be applied to build the same app:
+
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} {octicon}`workflow;2.5em;sd-mr-1 sd-animate-grow50` API context
-:link: api/index
+:::{grid-item-card} Stock Explorer - Callback API
+:img-top: https://assets.holoviz.org/panel/how_to/apis/stocks_callback.png
+:link: api/examples/stocks_callbacks
+:link-type: doc
+
+Build a stock explorer app using the `.param.watch` callback API.
+:::
+
+:::{grid-item-card} Stock Explorer - Declarative API
+:img-top: https://assets.holoviz.org/panel/how_to/apis/stocks_declarative.png
+:link: api/examples/stocks_declarative
+:link-type: doc
+
+Build a stock explorer app using the Param based declarative API.
+:::
+
+:::{grid-item-card} Stock Explorer - Reactive API
+:img-top: https://assets.holoviz.org/panel/how_to/apis/stocks_reactive.png
+:link: api/examples/stocks_reactive
+:link-type: doc
+
+Build a stock explorer app using the reactive API.
+:::
+
+:::{grid-item-card} Outlier Explorer - Declarative API
+:link: api/examples/outliers_declarative
 :link-type: doc
 
-Learn the pros and cons of Panel's different APIs.
+Build a simple outlier explorer app using the declarative API.
 :::
 
 ::::