crate · amotl · Feb 13, 2024 · Feb 13, 2024 · Feb 13, 2024 · Feb 13, 2024
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
diff --git a/.../handbook/getting-started/create-user.rst → docs/getting-started/create-user.rst b/.../handbook/getting-started/create-user.rst → docs/getting-started/create-user.rst
diff --git a/docs/handbook/getting-started/index.rst → docs/getting-started/index.rst b/docs/handbook/getting-started/index.rst → docs/getting-started/index.rst
@@ -14,6 +14,3 @@ A collection of CrateDB best practices and tips for common scenarios.
 
     introduction
     create-user
-    migrate/mysql
-    migrate/mongodb
-
diff --git a/...handbook/getting-started/introduction.rst → docs/getting-started/introduction.rst b/...handbook/getting-started/introduction.rst → docs/getting-started/introduction.rst
diff --git a/docs/admin/bootstrap-checks.rst → docs/handbook/bootstrap-checks.rst b/docs/admin/bootstrap-checks.rst → docs/handbook/bootstrap-checks.rst
diff --git a/docs/admin/clustering/index.rst → docs/handbook/clustering/index.rst b/docs/admin/clustering/index.rst → docs/handbook/clustering/index.rst
diff --git a/docs/admin/clustering/kubernetes.rst → docs/handbook/clustering/kubernetes.rst b/docs/admin/clustering/kubernetes.rst → docs/handbook/clustering/kubernetes.rst
diff --git a/.../clustering/logical-replication-setup.rst → .../clustering/logical-replication-setup.rst b/.../clustering/logical-replication-setup.rst → .../clustering/logical-replication-setup.rst
diff --git a/docs/admin/clustering/multi-node-setup.rst → .../handbook/clustering/multi-node-setup.rst b/docs/admin/clustering/multi-node-setup.rst → .../handbook/clustering/multi-node-setup.rst
diff --git a/docs/admin/clustering/multi-zone-setup.rst → .../handbook/clustering/multi-zone-setup.rst b/docs/admin/clustering/multi-zone-setup.rst → .../handbook/clustering/multi-zone-setup.rst
diff --git a/docs/admin/going-into-production.rst → docs/handbook/going-into-production.rst b/docs/admin/going-into-production.rst → docs/handbook/going-into-production.rst
diff --git a/docs/handbook/index.rst b/docs/handbook/index.rst
@@ -1,19 +1,38 @@
+.. _handbook:
 .. _handbooks:
 .. _user-handbooks:
 
-#########
-Handbooks
-#########
+########
+Handbook
+########
 
-A collection of CrateDB best practices and tips for common scenarios
-around the topics of sharding, partitioning, and performance tuning.
+This section of the documentation covers CrateDB database
+administration practices.
 
-.. rubric:: Table of contents
+.. toctree::
+    :maxdepth: 1
+
+    bootstrap-checks
+    going-into-production
+    troubleshooting/index
+
+
+Best practices and tips for common scenarios around the topics of
+clustering, sharding, partitioning, and performance tuning.
 
 .. toctree::
     :maxdepth: 1
 
-    getting-started/index
+    clustering/index
     sharding-partitioning
     performance/index
 
+
+Guidelines about upgrading CrateDB.
+
+.. toctree::
+    :maxdepth: 1
+
+    upgrade/planning
+    upgrade/rolling
+    upgrade/full
diff --git a/docs/admin/troubleshooting/crate-node.rst → docs/handbook/troubleshooting/crate-node.rst b/docs/admin/troubleshooting/crate-node.rst → docs/handbook/troubleshooting/crate-node.rst
diff --git a/docs/admin/troubleshooting/docker-jcmd.rst → .../handbook/troubleshooting/docker-jcmd.rst b/docs/admin/troubleshooting/docker-jcmd.rst → .../handbook/troubleshooting/docker-jcmd.rst
diff --git a/docs/admin/troubleshooting/index.rst → docs/handbook/troubleshooting/index.rst b/docs/admin/troubleshooting/index.rst → docs/handbook/troubleshooting/index.rst
diff --git a/docs/admin/troubleshooting/systables.rst → docs/handbook/troubleshooting/systables.rst b/docs/admin/troubleshooting/systables.rst → docs/handbook/troubleshooting/systables.rst
diff --git a/docs/admin/upgrade/full.rst → docs/handbook/upgrade/full.rst b/docs/admin/upgrade/full.rst → docs/handbook/upgrade/full.rst
diff --git a/docs/admin/upgrade/planning.rst → docs/handbook/upgrade/planning.rst b/docs/admin/upgrade/planning.rst → docs/handbook/upgrade/planning.rst
diff --git a/docs/admin/upgrade/rolling.rst → docs/handbook/upgrade/rolling.rst b/docs/admin/upgrade/rolling.rst → docs/handbook/upgrade/rolling.rst
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,169 @@
+(index)=
+(guides)=
+(howtos)=
+(tutorials)=
+
+# CrateDB Guides and Tutorials
+
+CrateDB is a distributed and scalable SQL database for storing and analyzing
+massive amounts of data in near real-time, even with complex queries. It is
+PostgreSQL-compatible, and based on Lucene. 
+
+This section of the documentation guides you how to use CrateDB in practice.
+
+
+::::{grid} 3
+:padding: 0
+
+
+:::{grid-item-card} Installation
+:link: install
+:link-type: ref
+:link-alt: Installing CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`download_for_offline;1.3em`
+:::
+
+
+:::{grid-item-card} Getting Started
+:link: getting-started
+:link-type: ref
+:link-alt: Getting started with CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`rocket_launch;1.3em`
+:::
+
+
+:::{grid-item-card} Handbook
+:link: handbook
+:link-type: ref
+:link-alt: CrateDB Handbook
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`auto_stories;1.3em`
+:::
+
+
+::::
+
+
+
+## Reference Architectures
+
+Reference architectures involving
+CrateDB for various use-cases.
+
+::::{grid} 1
+:padding: 0
+
+
+:::{grid-item-card} Reference Architectures
+:link: reference-architectures
+:link-type: ref
+:link-alt: Reference Architectures with CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+![](https://cratedb.com/hs-fs/hubfs/nativesql.png?width=480&name=nativesql.png)
+
+:::
+
+::::
+
+
+
+
+## Topics
+
+Native features of CrateDB paired with auxiliary software components provide
+optimal coverage of different application domains.
+
+::::{grid} 3
+:padding: 0
+
+
+:::{grid-item-card} Analysis and Visualization
+:link: analysis
+:link-type: ref
+:link-alt: Data Analysis and Visualization with CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`analytics;1.3em`
+:::
+
+
+:::{grid-item-card} Time Series Data
+:link: timeseries
+:link-type: ref
+:link-alt: Managing Time Series Data with CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`query_stats;1.3em`
+:::
+
+
+:::{grid-item-card} Machine Learning
+:link: machine-learning
+:link-type: ref
+:link-alt: Machine Learning with CrateDB
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+
+{material-outlined}`model_training;1.3em`
+:::
+
+
+::::
+
+
+
+```{toctree}
+:hidden:
+
+install/index
+getting-started/index
+handbook/index
+integrate/index
+
+reference-architectures/index
+t/analysis/index
+t/timeseries/index
+t/ml/index
+```
+
+
+:::{seealso}
+CrateDB and its documentation are open source projects. We host the source code and
+issue tracker on [GitHub].
+:::
+
+
+[GitHub]: https://github.com/crate/cratedb-guides
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/t/timeseries/azure-functions.rst → docs/integrate/azure-functions.rst b/docs/t/timeseries/azure-functions.rst → docs/integrate/azure-functions.rst
diff --git a/docs/integrate/index.md b/docs/integrate/index.md
@@ -0,0 +1,29 @@
+# Integrations
+
+A set of tutorials and guidelines how to integrate CrateDB with 3rd-party
+systems.
+
+
+```{toctree}
+:maxdepth: 1
+
+mongodb
+mysql
+```
+
+
+```{toctree}
+:maxdepth: 1
+
+kafka-connect
+azure-functions
+streamsets
+```
+
+
+:::{tip}
+Please also visit [Overview of CrateDB integration tutorials].
+:::
+
+
+[Overview of CrateDB integration tutorials]: https://community.cratedb.com/t/overview-of-cratedb-integration-tutorials/1015
diff --git a/docs/t/timeseries/kafka-connect.rst → docs/integrate/kafka-connect.rst b/docs/t/timeseries/kafka-connect.rst → docs/integrate/kafka-connect.rst
diff --git a/...dbook/getting-started/migrate/mongodb.rst → docs/integrate/mongodb.rst b/...dbook/getting-started/migrate/mongodb.rst → docs/integrate/mongodb.rst
@@ -2,9 +2,9 @@
 
 .. _migrating-mongodb:
 
-======================
-Migrating from MongoDB
-======================
+========================
+Import data from MongoDB
+========================
 
 .. rubric:: Table of contents
 

diff --git a/...andbook/getting-started/migrate/mysql.rst → docs/integrate/mysql.rst b/...andbook/getting-started/migrate/mysql.rst → docs/integrate/mysql.rst
@@ -2,9 +2,9 @@
 
 .. _migrating-mysql:
 
-====================
-Migrating from MySQL
-====================
+======================
+Import data from MySQL
+======================
 
 Various ways exist to migrate your existing data from MySQL_ to CrateDB_.
 However, these methods may differ in performance. A fast and reliable way to

diff --git a/docs/t/timeseries/streamsets.rst → docs/integrate/streamsets.rst b/docs/t/timeseries/streamsets.rst → docs/integrate/streamsets.rst
diff --git a/docs/reference-architectures/index.rst b/docs/reference-architectures/index.rst
@@ -1,3 +1,5 @@
+.. _reference-architectures:
+
 =======================
 Reference Architectures
 =======================

diff --git a/docs/t/timeseries/index.rst b/docs/t/timeseries/index.rst
@@ -1,3 +1,5 @@
+.. _timeseries:
+
 ################
 Time Series Data
 ################
@@ -13,21 +15,3 @@ tools, with respect to time-series use-cases.
 
     generate/index
     normalize-intervals
-
-
-.. rubric:: Ingestion
-
-.. toctree::
-    :maxdepth: 1
-
-    kafka-connect
-    streamsets
-
-
-.. rubric:: Enrichment
-
-.. toctree::
-    :maxdepth: 1
-
-    azure-functions
-