From 6bce2e24e4a045bbf0a586f2005a31a3752b912e Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Sat, 9 Aug 2025 11:59:47 +0200
Subject: [PATCH] Layout NG: Folder structure and naming things

The new structure revolves around "Topics", "Use Cases", and "Ingest".
Existing pages are relocated appropriately, specifically category-like
pages that provide guidance into relevant subsections.

- The "Application Domains" label is discouraged, let's just use "Topic"
  instead: s/domain/topic/

- Refactor category sections from `integrate/{etl,cdc,telemetry}` to
  `ingest`

- Refactor category sections and pages from
  `integrate/{bi,framework,lineage,testing,timeseries,visualize}` to
  `topic`

- Dissolve `reference-architectures` folder, refactor contents to
  `use/industrial`
---
 docs/{integrate => connect}/ide.md            |  13 +-
 docs/connect/index.md                         |   3 +-
 docs/domain/index.md                          | 142 ------------------
 docs/index.md                                 |  11 +-
 docs/{integrate => ingest}/cdc/index.md       |   9 +-
 .../etl/azure-functions.rst                   |   0
 .../etl/iceberg-risingwave.md                 |   0
 docs/{integrate => ingest}/etl/index.md       |  82 ++--------
 docs/{integrate => ingest}/etl/mongodb.md     |   0
 docs/{integrate => ingest}/etl/mysql.rst      |   0
 docs/{integrate => ingest}/etl/streamsets.rst |   0
 docs/ingest/index.md                          |  10 ++
 docs/{integrate => ingest}/telemetry/index.md |  13 +-
 docs/integrate/index.md                       |  53 +++++--
 docs/integrate/metabase/index.md              |   1 +
 docs/integrate/rill/index.md                  |   1 +
 docs/reference-architectures/index.rst        |  17 ---
 docs/{integrate => topic}/bi/index.md         |  19 +--
 .../framework.md => topic/framework/index.md} |  15 +-
 docs/topic/index.md                           |  82 ++++++++++
 docs/{integrate => topic}/lineage/index.md    |   6 +-
 docs/{domain => topic}/ml/index.md            |   0
 docs/{domain => topic}/ml/r.rst               |   0
 docs/{domain => topic}/ml/tensorflow.rst      |   0
 .../testing.md => topic/testing/index.md}     |   0
 docs/{domain => topic}/timeseries/advanced.md |   0
 .../timeseries/fundamentals.md                |   0
 .../timeseries/generate/cli.rst               |   0
 .../timeseries/generate/go.rst                |   0
 .../timeseries/generate/index.rst             |   0
 .../timeseries/generate/node.rst              |   0
 .../timeseries/generate/python.rst            |   0
 docs/{domain => topic}/timeseries/index.md    |   0
 .../timeseries/learn/normalize-pandas.rst     |   0
 .../timeseries/learn/query.md                 |   0
 .../timeseries/learn/with-metadata.md         |   0
 docs/{domain => topic}/timeseries/longterm.md |   0
 docs/{domain => topic}/timeseries/video.md    |   0
 docs/{integrate => topic}/visualize/index.md  |  18 +--
 docs/{domain => use}/analytics/index.md       |   0
 docs/use/index.md                             |  82 ++++++++++
 .../industrial/azure-iot.rst}                 |   8 +-
 .../industrial}/distributed-ml.rst            |   0
 docs/{domain => use}/industrial/index.md      |  13 ++
 docs/{ => use}/migrate/index.md               |   0
 docs/{ => use}/migrate/rockset/index.md       |   0
 docs/{ => use}/migrate/rockset/query.md       |   0
 docs/{domain => use}/telemetry/index.md       |   0
 48 files changed, 278 insertions(+), 320 deletions(-)
 rename docs/{integrate => connect}/ide.md (69%)
 delete mode 100644 docs/domain/index.md
 rename docs/{integrate => ingest}/cdc/index.md (96%)
 rename docs/{integrate => ingest}/etl/azure-functions.rst (100%)
 rename docs/{integrate => ingest}/etl/iceberg-risingwave.md (100%)
 rename docs/{integrate => ingest}/etl/index.md (80%)
 rename docs/{integrate => ingest}/etl/mongodb.md (100%)
 rename docs/{integrate => ingest}/etl/mysql.rst (100%)
 rename docs/{integrate => ingest}/etl/streamsets.rst (100%)
 rename docs/{integrate => ingest}/telemetry/index.md (81%)
 delete mode 100644 docs/reference-architectures/index.rst
 rename docs/{integrate => topic}/bi/index.md (59%)
 rename docs/{integrate/framework.md => topic/framework/index.md} (88%)
 create mode 100644 docs/topic/index.md
 rename docs/{integrate => topic}/lineage/index.md (97%)
 rename docs/{domain => topic}/ml/index.md (100%)
 rename docs/{domain => topic}/ml/r.rst (100%)
 rename docs/{domain => topic}/ml/tensorflow.rst (100%)
 rename docs/{integrate/testing.md => topic/testing/index.md} (100%)
 rename docs/{domain => topic}/timeseries/advanced.md (100%)
 rename docs/{domain => topic}/timeseries/fundamentals.md (100%)
 rename docs/{domain => topic}/timeseries/generate/cli.rst (100%)
 rename docs/{domain => topic}/timeseries/generate/go.rst (100%)
 rename docs/{domain => topic}/timeseries/generate/index.rst (100%)
 rename docs/{domain => topic}/timeseries/generate/node.rst (100%)
 rename docs/{domain => topic}/timeseries/generate/python.rst (100%)
 rename docs/{domain => topic}/timeseries/index.md (100%)
 rename docs/{domain => topic}/timeseries/learn/normalize-pandas.rst (100%)
 rename docs/{domain => topic}/timeseries/learn/query.md (100%)
 rename docs/{domain => topic}/timeseries/learn/with-metadata.md (100%)
 rename docs/{domain => topic}/timeseries/longterm.md (100%)
 rename docs/{domain => topic}/timeseries/video.md (100%)
 rename docs/{integrate => topic}/visualize/index.md (57%)
 rename docs/{domain => use}/analytics/index.md (100%)
 create mode 100644 docs/use/index.md
 rename docs/{reference-architectures/cratedb-azure-iot.rst => use/industrial/azure-iot.rst} (87%)
 rename docs/{reference-architectures => use/industrial}/distributed-ml.rst (100%)
 rename docs/{domain => use}/industrial/index.md (98%)
 rename docs/{ => use}/migrate/index.md (100%)
 rename docs/{ => use}/migrate/rockset/index.md (100%)
 rename docs/{ => use}/migrate/rockset/query.md (100%)
 rename docs/{domain => use}/telemetry/index.md (100%)

diff --git a/docs/integrate/ide.md b/docs/connect/ide.md
similarity index 69%
rename from docs/integrate/ide.md
rename to docs/connect/ide.md
index 96fe4b34..18f4f5da 100644
--- a/docs/integrate/ide.md
+++ b/docs/connect/ide.md
@@ -1,13 +1,14 @@
 (ide)=
-
+(connect-ide)=
 # Database IDEs
 
 Mostly through its PostgreSQL interface, CrateDB supports working with popular
 database IDE (Integrated Development Environment) applications.
 
-```{toctree}
-:maxdepth: 2
+## DataGrip
+
+- {ref}`datagrip`
+
+## DBeaver
 
-datagrip/index
-dbeaver/index
-```
+- {ref}`dbeaver`
diff --git a/docs/connect/index.md b/docs/connect/index.md
index 62b927f0..94069e65 100644
--- a/docs/connect/index.md
+++ b/docs/connect/index.md
@@ -101,8 +101,9 @@ Connection examples.
 :hidden:
 
 configure
-Drivers <drivers>
 CLI programs <cli>
+ide
+Drivers <drivers>
 DataFrame libraries <df/index>
 ORM libraries <orm>
 ```
diff --git a/docs/domain/index.md b/docs/domain/index.md
deleted file mode 100644
index 666d0dad..00000000
--- a/docs/domain/index.md
+++ /dev/null
@@ -1,142 +0,0 @@
-(domain)=
-(domains)=
-
-# Application Domains
-
-Learn how to apply CrateDB within different use case scenarios, and how others
-are using CrateDB to build data management solutions and platforms.
-
-{tags-primary}`Full-Text Search`
-{tags-primary}`Document / Object / JSON`
-{tags-primary}`Long Term Metrics Store`
-{tags-primary}`Industrial Data`
-{tags-primary}`Time Series Data`
-{tags-primary}`Machine Learning`
-:::
-
-
-```{toctree}
-:maxdepth: 1
-:hidden:
-
-telemetry/index
-analytics/index
-industrial/index
-timeseries/index
-Machine Learning <ml/index>
-```
-
-
-:::{rubric} Traditional Use Cases
-:::
-
-CrateDB is being developed in an open-source spirit, and closely together
-with its users and customers. Learn about application scenarios where CrateDB
-derives many foundational features from.
-
-::::{grid} 1 2 2 2
-:margin: 4 4 0 0
-:padding: 0
-:gutter: 2
-
-
-:::{grid-item-card} {material-outlined}`manage_history;2em` Long Term Metrics Store
-:link: metrics-store
-:link-type: ref
-:link-alt: Using CrateDB as a long term metrics store
-
-Store metrics and telemetry data for the long term, with the benefits of
-using standard database interfaces, SQL query language, and horizontal
-scalability through clustering as you go.
-+++
-**What's inside:**
-Never retire old records to cold storage,
-always have them ready for historical analysis.
-:::
-
-
-:::{grid-item-card} {material-outlined}`analytics;2em` Raw-Data Analytics
-:link: analytics
-:link-type: ref
-:link-alt: About CrateDB's analytics features
-
-CrateDB provides real-time analytics on raw data.
-Learn how others are successfully running real-time multi tenant data
-analytics applications on top of billions of records.
-+++
-**What's inside:**
-If you absolutely must keep the records, because they are unique,
-downsampling is not an option.
-:::
-
-
-:::{grid-item-card} {material-outlined}`precision_manufacturing;2em` Industrial Data
-:link: industrial
-:link-type: ref
-:link-alt: Use CrateDB in industrial data platforms
-
-Learn how others are successfully using CrateDB within industrial,
-engineering, manufacturing, production, and logistics domains.
-+++
-**What's inside:**
-About the unique challenges and complexities of industrial big data.
-:::
-
-
-::::
-
-
-:::{rubric} Time Series Data Analysis and Machine Learning
-:::
-
-Apply procedures from advanced analysis, scientific computing, and other
-technology domains to your data without further ado.
-
-::::{grid} 1 2 2 2
-:margin: 4 4 0 0
-:padding: 0
-:gutter: 2
-
-
-:::{grid-item-card} {material-outlined}`stacked_line_chart;2em` Time Series Data
-:link: timeseries
-:link-type: ref
-:link-alt: About CrateDB for time series data analysis
-
-Learn how to use CrateDB for time series use-cases,
-and how to apply time series modeling and analysis procedures
-to your data.
-+++
-**What's inside:**
-Tutorials about data-import and -export, statistical
-analysis, data visualization, and machine learning.
-:::
-
-
-:::{grid-item-card} {material-outlined}`model_training;2em` Machine Learning
-:link: machine-learning
-:link-type: ref
-:link-alt: About CrateDB for machine learning applications
-
-Learn how to integrate CrateDB with machine learning frameworks and tools.
-+++
-**What's inside:**
-Use CrateDB with LangChain, LlamaIndex, MLflow, PyCaret, scikit-learn,
-or TensorFlow.
-:::
-
-
-::::
-
-
-:::{seealso} **Related Features:**
-[](#document) •
-[](#fulltext) •
-[](#geospatial) •
-[](#generated-columns) •
-[](#udf)
-:::
-
-
-```{include} /_include/styles.html
-```
diff --git a/docs/index.md b/docs/index.md
index d8a8bbf9..8758b928 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -301,21 +301,20 @@ use-cases.
 ::::
 
 
+
 ```{toctree}
 :hidden:
 
 install/index
 connect/index
 getting-started
-Ingestion <ingest/index>
 feature/index
+Ingestion <ingest/index>
+topic/index
+use/index
+integrate/index
 admin/index
 performance/index
-
-domain/index
-integrate/index
-migrate/index
-reference-architectures/index
 ```
 
 
diff --git a/docs/integrate/cdc/index.md b/docs/ingest/cdc/index.md
similarity index 96%
rename from docs/integrate/cdc/index.md
rename to docs/ingest/cdc/index.md
index 249c426c..8b8fd542 100644
--- a/docs/integrate/cdc/index.md
+++ b/docs/ingest/cdc/index.md
@@ -8,7 +8,7 @@
 You have a variety of options to connect and integrate with 3rd-party
 CDC applications, mostly using [CrateDB's PostgreSQL interface].
 
-CrateDB also provides a few native adapter components, that can be used
+CrateDB also provides a few native adapter components that can be used
 to leverage its advanced features. 
 
 This documentation section lists corresponding CDC applications and
@@ -56,11 +56,7 @@ Kinesis Stream, and consume that from an adapter to a consolidation database.
 
 ## Debezium
 
-:::{toctree}
-:maxdepth: 1
-
-../debezium/index
-:::
+- {ref}`debezium`
 
 (cdc-dynamodb)=
 ## DynamoDB
@@ -100,5 +96,4 @@ lives.
 - {ref}`streamsets`
 
 
-
 [StreamSets Data Collector]: https://www.softwareag.com/en_corporate/platform/integration-apis/data-collector-engine.html
diff --git a/docs/integrate/etl/azure-functions.rst b/docs/ingest/etl/azure-functions.rst
similarity index 100%
rename from docs/integrate/etl/azure-functions.rst
rename to docs/ingest/etl/azure-functions.rst
diff --git a/docs/integrate/etl/iceberg-risingwave.md b/docs/ingest/etl/iceberg-risingwave.md
similarity index 100%
rename from docs/integrate/etl/iceberg-risingwave.md
rename to docs/ingest/etl/iceberg-risingwave.md
diff --git a/docs/integrate/etl/index.md b/docs/ingest/etl/index.md
similarity index 80%
rename from docs/integrate/etl/index.md
rename to docs/ingest/etl/index.md
index 6999c7fa..64143cbc 100644
--- a/docs/integrate/etl/index.md
+++ b/docs/ingest/etl/index.md
@@ -1,7 +1,7 @@
 (etl)=
 (io)=
 (import-export)=
-# Load and Export
+# Load and Export (ETL)
 
 :::{include} /_include/links.md
 :::
@@ -19,27 +19,15 @@ Please also have a look at support for [](#cdc) solutions.
 
 ## Apache Airflow / Astronomer
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-airflow/index
-:::
+- {ref}`apache-airflow`
 
 ## Apache Flink
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-flink/index
-:::
+- {ref}`apache-flink`
 
 ## Apache Hop
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-hop/index
-:::
+- {ref}`apache-hop`
 
 ## Apache Iceberg / RisingWave
 :::{div}
@@ -54,19 +42,11 @@ iceberg-risingwave
 
 ## Apache Kafka
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-kafka/index
-:::
+- {ref}`apache-kafka`
 
 ## Apache NiFi
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-nifi/index
-:::
+- {ref}`apache-nifi`
 
 ## AWS DMS
 
@@ -116,12 +96,7 @@ azure-functions
 
 ## dbt
 
-:::{toctree}
-:maxdepth: 1
-
-../dbt/index
-:::
-
+- {ref}`dbt`
 
 ## DynamoDB
 :::{div}
@@ -132,38 +107,19 @@ azure-functions
 
 ## Estuary
 
-:::{toctree}
-:maxdepth: 1
-
-../estuary/index
-:::
-
+- {ref}`estuary`
 
 ## InfluxDB
 
 - {ref}`integrate-influxdb`
 
-```{toctree}
-:hidden:
-
-../influxdb/index
-```
-
 ## Kestra
 
-:::{toctree}
-:maxdepth: 1
-
-../kestra/index
-:::
+- {ref}`kestra`
 
 ## Meltano
 
-:::{toctree}
-:maxdepth: 1
-
-../meltano/index
-:::
+- {ref}`meltano`
 
 ## MongoDB
 :::{div}
@@ -190,27 +146,15 @@ mysql
 
 ## Node-RED
 
-:::{toctree}
-:maxdepth: 1
-
-../node-red/index
-:::
+- {ref}`node-red`
 
 ## RisingWave
 
-:::{toctree}
-:maxdepth: 1
-
-../risingwave/index
-:::
+- {ref}`risingwave`
 
 ## SQL Server Integration Services
 
-:::{toctree}
-:maxdepth: 1
-
-../sql-server/index
-:::
+- {ref}`sql-server`
 
 ## StreamSets
 
diff --git a/docs/integrate/etl/mongodb.md b/docs/ingest/etl/mongodb.md
similarity index 100%
rename from docs/integrate/etl/mongodb.md
rename to docs/ingest/etl/mongodb.md
diff --git a/docs/integrate/etl/mysql.rst b/docs/ingest/etl/mysql.rst
similarity index 100%
rename from docs/integrate/etl/mysql.rst
rename to docs/ingest/etl/mysql.rst
diff --git a/docs/integrate/etl/streamsets.rst b/docs/ingest/etl/streamsets.rst
similarity index 100%
rename from docs/integrate/etl/streamsets.rst
rename to docs/ingest/etl/streamsets.rst
diff --git a/docs/ingest/index.md b/docs/ingest/index.md
index c681e832..9ca48032 100644
--- a/docs/ingest/index.md
+++ b/docs/ingest/index.md
@@ -66,3 +66,13 @@ Supported industry-standard frameworks and paradigms.
 ::::
 
 :::::
+
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+etl/index
+cdc/index
+telemetry/index
+```
diff --git a/docs/integrate/telemetry/index.md b/docs/ingest/telemetry/index.md
similarity index 81%
rename from docs/integrate/telemetry/index.md
rename to docs/ingest/telemetry/index.md
index 2b2766ce..4b5f4f86 100644
--- a/docs/integrate/telemetry/index.md
+++ b/docs/ingest/telemetry/index.md
@@ -12,17 +12,8 @@ scenarios. CrateDB offers corresponding integration adapters.
 
 ## Prometheus
 
-:::{toctree}
-:maxdepth: 1
-
-../prometheus/index
-:::
-
+- {ref}`prometheus`
 
 ## Telegraf
 
-:::{toctree}
-:maxdepth: 1
-
-../telegraf/index
-:::
+- {ref}`telegraf`
diff --git a/docs/integrate/index.md b/docs/integrate/index.md
index 464fee8d..f0f85f58 100644
--- a/docs/integrate/index.md
+++ b/docs/integrate/index.md
@@ -9,26 +9,47 @@ This documentation section lists applications, frameworks, and libraries,
 which can be used together with CrateDB, and outlines how to use them
 optimally.
 
-```{toctree}
-:maxdepth: 2
-
-ide
-Frameworks <framework>
-etl/index
-cdc/index
-mcp/index
-Metrics and Telemetry <telemetry/index>
-Data Visualization <visualize/index>
-bi/index
-lineage/index
-testing
-```
-
 :::{tip}
 Please also visit the [Overview of CrateDB integration tutorials].
 :::
 
-
+:::{toctree}
+:maxdepth: 1
+
+apache-airflow/index
+apache-flink/index
+apache-hop/index
+apache-kafka/index
+apache-nifi/index
+apache-superset/index
+cluvio/index
+datagrip/index
+dbeaver/index
+dbt/index
+debezium/index
+django/index
+estuary/index
+explo/index
+gradio/index
+grafana/index
+influxdb/index
+kestra/index
+marquez/index
+mcp/index
+meltano/index
+metabase/index
+node-red/index
+plotly/index
+powerbi/index
+prometheus/index
+pyviz/index
+rill/index
+risingwave/index
+sql-server/index
+streamlit/index
+tableau/index
+telegraf/index
+:::
 
 
 [CrateDB's PostgreSQL interface]: inv:crate-reference#interface-postgresql
diff --git a/docs/integrate/metabase/index.md b/docs/integrate/metabase/index.md
index 90ca0641..2563a645 100644
--- a/docs/integrate/metabase/index.md
+++ b/docs/integrate/metabase/index.md
@@ -1,3 +1,4 @@
+(metabase)=
 # Metabase
 
 ```{div}
diff --git a/docs/integrate/rill/index.md b/docs/integrate/rill/index.md
index cecf21d9..d2d86847 100644
--- a/docs/integrate/rill/index.md
+++ b/docs/integrate/rill/index.md
@@ -1,3 +1,4 @@
+(rill)=
 # Rill
 
 :::{rubric} About
diff --git a/docs/reference-architectures/index.rst b/docs/reference-architectures/index.rst
deleted file mode 100644
index 17bf636f..00000000
--- a/docs/reference-architectures/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. _reference-architectures:
-
-=======================
-Reference Architectures
-=======================
-
-This section of the documentation covers reference architectures involving
-CrateDB for various use-cases.
-
-.. rubric:: Azure
-
-.. toctree::
-   :maxdepth: 1
-
-   cratedb-azure-iot
-   distributed-ml
-
diff --git a/docs/integrate/bi/index.md b/docs/topic/bi/index.md
similarity index 59%
rename from docs/integrate/bi/index.md
rename to docs/topic/bi/index.md
index 3ec9b23c..3bb6beed 100644
--- a/docs/integrate/bi/index.md
+++ b/docs/topic/bi/index.md
@@ -10,25 +10,12 @@ analytics and intelligence software.
 
 ## PowerBI
 
-```{toctree}
-:maxdepth: 1
-
-../powerbi/index
-```
+- {ref}`powerbi`
 
 ## Rill
 
-```{toctree}
-:maxdepth: 1
-
-../rill/index
-```
-
+- {ref}`rill`
 
 ## Tableau
 
-```{toctree}
-:maxdepth: 1
-
-../tableau/index
-```
+- {ref}`tableau`
diff --git a/docs/integrate/framework.md b/docs/topic/framework/index.md
similarity index 88%
rename from docs/integrate/framework.md
rename to docs/topic/framework/index.md
index 43cff60a..973e8fac 100644
--- a/docs/integrate/framework.md
+++ b/docs/topic/framework/index.md
@@ -22,13 +22,8 @@ A few quick examples about how to use selected frameworks together with CrateDB.
 
 :::::
 
-
-:::{toctree}
-:maxdepth: 1
-
-django/index
-gradio/index
-plotly/index
-pyviz/index
-streamlit/index
-:::
+- {ref}`django`
+- {ref}`gradio`
+- {ref}`plotly`
+- {ref}`pyviz`
+- {ref}`streamlit`
diff --git a/docs/topic/index.md b/docs/topic/index.md
new file mode 100644
index 00000000..eb9d12d7
--- /dev/null
+++ b/docs/topic/index.md
@@ -0,0 +1,82 @@
+(domain)=
+(domains)=
+
+# Topics
+
+Learn how to apply CrateDB within different use case scenarios.
+
+{tags-primary}`Time Series Data`
+{tags-primary}`Machine Learning`
+{tags-primary}`Full-Text Search`
+{tags-primary}`Document / Object / JSON`
+:::
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+Business Intelligence <bi/index>
+Data Lineage <lineage/index>
+Data Visualization <visualize/index>
+Machine Learning <ml/index>
+Programming Frameworks <framework/index>
+Software Testing <testing/index>
+Time Series Data <timeseries/index>
+```
+
+
+:::{rubric} Time Series Data Analysis and Machine Learning
+:::
+
+Apply procedures from advanced analysis, scientific computing, and other
+technology domains to your data without further ado.
+
+::::{grid} 1 2 2 2
+:margin: 4 4 0 0
+:padding: 0
+:gutter: 2
+
+
+:::{grid-item-card} {material-outlined}`stacked_line_chart;2em` Time Series Data
+:link: timeseries
+:link-type: ref
+:link-alt: About CrateDB for time series data analysis
+
+Learn how to use CrateDB for time series use-cases,
+and how to apply time series modeling and analysis procedures
+to your data.
++++
+**What's inside:**
+Tutorials about data-import and -export, statistical
+analysis, data visualization, and machine learning.
+:::
+
+
+:::{grid-item-card} {material-outlined}`model_training;2em` Machine Learning
+:link: machine-learning
+:link-type: ref
+:link-alt: About CrateDB for machine learning applications
+
+Learn how to integrate CrateDB with machine learning frameworks and tools.
++++
+**What's inside:**
+Use CrateDB with LangChain, LlamaIndex, MLflow, PyCaret, scikit-learn,
+or TensorFlow.
+:::
+
+
+::::
+
+
+:::{seealso} **Related Features:**
+{ref}`Document / Object / JSON <document>` •
+{ref}`Full-Text Search <fulltext>` •
+{ref}`Geospatial Data <geospatial>` •
+{ref}`Generated Columns <generated-columns>` •
+{ref}`User-Defined Functions <udf>`
+:::
+
+
+```{include} /_include/styles.html
+```
diff --git a/docs/integrate/lineage/index.md b/docs/topic/lineage/index.md
similarity index 97%
rename from docs/integrate/lineage/index.md
rename to docs/topic/lineage/index.md
index 7631813d..1c981a0c 100644
--- a/docs/integrate/lineage/index.md
+++ b/docs/topic/lineage/index.md
@@ -38,11 +38,7 @@ lineage data, and the approach for collecting lineage data from external systems
 ## Solutions
 Data lineage solutions tested with CrateDB.
 
-```{toctree}
-:maxdepth: 1
-
-../marquez/index
-```
+- {ref}`marquez`
 
 
 [Data lineage]: https://en.wikipedia.org/wiki/Data_lineage
diff --git a/docs/domain/ml/index.md b/docs/topic/ml/index.md
similarity index 100%
rename from docs/domain/ml/index.md
rename to docs/topic/ml/index.md
diff --git a/docs/domain/ml/r.rst b/docs/topic/ml/r.rst
similarity index 100%
rename from docs/domain/ml/r.rst
rename to docs/topic/ml/r.rst
diff --git a/docs/domain/ml/tensorflow.rst b/docs/topic/ml/tensorflow.rst
similarity index 100%
rename from docs/domain/ml/tensorflow.rst
rename to docs/topic/ml/tensorflow.rst
diff --git a/docs/integrate/testing.md b/docs/topic/testing/index.md
similarity index 100%
rename from docs/integrate/testing.md
rename to docs/topic/testing/index.md
diff --git a/docs/domain/timeseries/advanced.md b/docs/topic/timeseries/advanced.md
similarity index 100%
rename from docs/domain/timeseries/advanced.md
rename to docs/topic/timeseries/advanced.md
diff --git a/docs/domain/timeseries/fundamentals.md b/docs/topic/timeseries/fundamentals.md
similarity index 100%
rename from docs/domain/timeseries/fundamentals.md
rename to docs/topic/timeseries/fundamentals.md
diff --git a/docs/domain/timeseries/generate/cli.rst b/docs/topic/timeseries/generate/cli.rst
similarity index 100%
rename from docs/domain/timeseries/generate/cli.rst
rename to docs/topic/timeseries/generate/cli.rst
diff --git a/docs/domain/timeseries/generate/go.rst b/docs/topic/timeseries/generate/go.rst
similarity index 100%
rename from docs/domain/timeseries/generate/go.rst
rename to docs/topic/timeseries/generate/go.rst
diff --git a/docs/domain/timeseries/generate/index.rst b/docs/topic/timeseries/generate/index.rst
similarity index 100%
rename from docs/domain/timeseries/generate/index.rst
rename to docs/topic/timeseries/generate/index.rst
diff --git a/docs/domain/timeseries/generate/node.rst b/docs/topic/timeseries/generate/node.rst
similarity index 100%
rename from docs/domain/timeseries/generate/node.rst
rename to docs/topic/timeseries/generate/node.rst
diff --git a/docs/domain/timeseries/generate/python.rst b/docs/topic/timeseries/generate/python.rst
similarity index 100%
rename from docs/domain/timeseries/generate/python.rst
rename to docs/topic/timeseries/generate/python.rst
diff --git a/docs/domain/timeseries/index.md b/docs/topic/timeseries/index.md
similarity index 100%
rename from docs/domain/timeseries/index.md
rename to docs/topic/timeseries/index.md
diff --git a/docs/domain/timeseries/learn/normalize-pandas.rst b/docs/topic/timeseries/learn/normalize-pandas.rst
similarity index 100%
rename from docs/domain/timeseries/learn/normalize-pandas.rst
rename to docs/topic/timeseries/learn/normalize-pandas.rst
diff --git a/docs/domain/timeseries/learn/query.md b/docs/topic/timeseries/learn/query.md
similarity index 100%
rename from docs/domain/timeseries/learn/query.md
rename to docs/topic/timeseries/learn/query.md
diff --git a/docs/domain/timeseries/learn/with-metadata.md b/docs/topic/timeseries/learn/with-metadata.md
similarity index 100%
rename from docs/domain/timeseries/learn/with-metadata.md
rename to docs/topic/timeseries/learn/with-metadata.md
diff --git a/docs/domain/timeseries/longterm.md b/docs/topic/timeseries/longterm.md
similarity index 100%
rename from docs/domain/timeseries/longterm.md
rename to docs/topic/timeseries/longterm.md
diff --git a/docs/domain/timeseries/video.md b/docs/topic/timeseries/video.md
similarity index 100%
rename from docs/domain/timeseries/video.md
rename to docs/topic/timeseries/video.md
diff --git a/docs/integrate/visualize/index.md b/docs/topic/visualize/index.md
similarity index 57%
rename from docs/integrate/visualize/index.md
rename to docs/topic/visualize/index.md
index e3ca2d7c..e2b41bfa 100644
--- a/docs/integrate/visualize/index.md
+++ b/docs/topic/visualize/index.md
@@ -8,14 +8,10 @@ visualizing data stored inside CrateDB, mostly dashboarding.
 :::{include} /_include/links.md
 :::
 
-:::{toctree}
-:maxdepth: 1
-
-../apache-superset/index
-../cluvio/index
-../explo/index
-../grafana/index
-../pyviz/index
-../metabase/index
-../plotly/index
-:::
+- {ref}`cluvio`
+- {ref}`explo`
+- {ref}`grafana`
+- {ref}`metabase`
+- {ref}`plotly`
+- {ref}`pyviz`
+- {ref}`superset`
diff --git a/docs/domain/analytics/index.md b/docs/use/analytics/index.md
similarity index 100%
rename from docs/domain/analytics/index.md
rename to docs/use/analytics/index.md
diff --git a/docs/use/index.md b/docs/use/index.md
new file mode 100644
index 00000000..63b3040b
--- /dev/null
+++ b/docs/use/index.md
@@ -0,0 +1,82 @@
+(use-cases)=
+# Use Cases
+
+Learn how others are using CrateDB to build data management solutions and platforms.
+
+{tags-primary}`Raw-Data Analytics`
+{tags-primary}`Industrial Data`
+{tags-primary}`Long-Term Metrics Store`
+:::
+
+:::{rubric} Traditional Use Cases
+:::
+
+CrateDB is being developed in an open-source spirit, and closely together
+with its users and customers. Learn about application scenarios where CrateDB
+derives many foundational features from.
+
+::::{grid} 1 2 2 2
+:margin: 4 4 0 0
+:padding: 0
+:gutter: 2
+
+
+:::{grid-item-card} {material-outlined}`analytics;2em` Raw-Data Analytics
+:link: analytics
+:link-type: ref
+:link-alt: About CrateDB's analytics features
+
+CrateDB provides real-time analytics on raw data.
+Learn how others are successfully running real-time multi-tenant data
+analytics applications on top of billions of records.
++++
+**What's inside:**
+If you absolutely must keep the records, because they are unique,
+downsampling is not an option.
+:::
+
+
+:::{grid-item-card} {material-outlined}`precision_manufacturing;2em` Industrial Data
+:link: industrial
+:link-type: ref
+:link-alt: Use CrateDB in industrial data platforms
+
+Learn how others are successfully using CrateDB within industrial,
+engineering, manufacturing, production, and logistics domains.
++++
+**What's inside:**
+About the unique challenges and complexities of industrial big data.
+:::
+
+
+:::{grid-item-card} {material-outlined}`manage_history;2em` Long-Term Metrics Store
+:link: metrics-store
+:link-type: ref
+:link-alt: Using CrateDB as a long-term metrics store
+
+Store metrics and telemetry data for the long term, with the benefits of
+using standard database interfaces, SQL query language, and horizontal
+scalability through clustering as you go.
++++
+**What's inside:**
+Never retire old records to cold storage,
+always have them ready for historical analysis.
+:::
+
+
+::::
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+analytics/index
+industrial/index
+telemetry/index
+migrate/index
+```
+
+
+```{include} /_include/styles.html
+```
diff --git a/docs/reference-architectures/cratedb-azure-iot.rst b/docs/use/industrial/azure-iot.rst
similarity index 87%
rename from docs/reference-architectures/cratedb-azure-iot.rst
rename to docs/use/industrial/azure-iot.rst
index f4e9315c..3a7f0d2d 100644
--- a/docs/reference-architectures/cratedb-azure-iot.rst
+++ b/docs/use/industrial/azure-iot.rst
@@ -1,6 +1,8 @@
-====================
-CrateDB on Azure IoT
-====================
+.. _azure-iot:
+
+======================
+Azure IoT with CrateDB
+======================
 
 
 Architecture
diff --git a/docs/reference-architectures/distributed-ml.rst b/docs/use/industrial/distributed-ml.rst
similarity index 100%
rename from docs/reference-architectures/distributed-ml.rst
rename to docs/use/industrial/distributed-ml.rst
diff --git a/docs/domain/industrial/index.md b/docs/use/industrial/index.md
similarity index 98%
rename from docs/domain/industrial/index.md
rename to docs/use/industrial/index.md
index 34500ea4..73a9652a 100644
--- a/docs/domain/industrial/index.md
+++ b/docs/use/industrial/index.md
@@ -50,6 +50,19 @@ on top.
   [](#machine-learning)
 
 
+(reference-architectures)=
+## Reference Architectures
+
+Reference architectures showing how CrateDB can be used in various use cases.
+
+:::{toctree}
+:maxdepth: 1
+
+Azure IoT <azure-iot>
+Machine Learning <distributed-ml>
+:::
+
+
 (abb)=
 ## ABB Insights
 
diff --git a/docs/migrate/index.md b/docs/use/migrate/index.md
similarity index 100%
rename from docs/migrate/index.md
rename to docs/use/migrate/index.md
diff --git a/docs/migrate/rockset/index.md b/docs/use/migrate/rockset/index.md
similarity index 100%
rename from docs/migrate/rockset/index.md
rename to docs/use/migrate/rockset/index.md
diff --git a/docs/migrate/rockset/query.md b/docs/use/migrate/rockset/query.md
similarity index 100%
rename from docs/migrate/rockset/query.md
rename to docs/use/migrate/rockset/query.md
diff --git a/docs/domain/telemetry/index.md b/docs/use/telemetry/index.md
similarity index 100%
rename from docs/domain/telemetry/index.md
rename to docs/use/telemetry/index.md