Diátaxis: Index how-to guides and tutorials

docs/_include/links.md

@@ -15,6 +15,7 @@
 [CTE]: inv:crate-reference#sql_dql_with
 [CrateDB BLOBs]: inv:crate-reference:*:label#blob_support
 [CrateDB Cloud]: inv:cloud:*:label#index
+[CrateDB Cloud Console]: https://console.cratedb.cloud/
 [CrateDB JDBC Driver]: https://cratedb.com/docs/jdbc/
 [CrateDB Reference Manual]: inv:crate-reference:*:label#index
 [CrateDB Self-Managed]: https://cratedb.com/product/self-managed

docs/feature/document/index.md

@@ -427,5 +427,5 @@ and about OBJECT indexing.
 :maxdepth: 1
 :hidden:
 
-Usage <usage>
+Tutorial <tutorial>
 ```

docs/feature/document/usage.md → docs/feature/document/tutorial.md

@@ -1,11 +1,15 @@
 (objects-basics)=
 (objects-usage)=
+(objects-tutorial-marketing)=
 
 # Objects: Analyzing Marketing Data
 
+:::{include} /_include/links.md
+:::
+
 Marketers often need to handle multi-structured data from different platforms.
 CrateDB's dynamic `OBJECT` data type allows us to store and analyze this complex,
-nested data efficiently. In this usage guide, we'll explore how to leverage this
+nested data efficiently. In this tutorial, we'll explore how to leverage this
 feature in marketing data analysis, along with the use of generated columns to
 parse and manage URLs.
 
@@ -28,6 +32,12 @@ To begin, let's create the schema for this dataset.
 
 ## Creating the Table
 
+:::{div}
+The fastest and easiest way to get started with CrateDB is by deploying a
+free tier (CRFREE) cluster on [CrateDB Cloud][CrateDB Cloud Console]. Otherwise,
+see the {ref}`install` section to run CrateDB yourself.
+:::
+
 CrateDB uses SQL, the most popular query language for database management. To
 store the marketing data, create a table with columns tailored to the
 dataset using the `CREATE TABLE` command:
@@ -125,5 +135,5 @@ GROUP BY 1
 ORDER BY 2 DESC;
 :::
 
-In this usage guide, we explored the versatility and power of CrateDB's dynamic
+In this tutorial, we explored the versatility and power of CrateDB's dynamic
 `OBJECT` data type for handling complex, nested marketing data.

docs/feature/search/fts/index.md

@@ -285,7 +285,7 @@ files, and corresponding technical backgrounds about their implementations.
 The usage guide illustrates the BM25 ranking algorithm for information retrieval,
 by exploring how to manage a dataset of Netflix titles.
 
-{hyper-navigate}`Netflix Tutorial <search-fts-usage>`
+{hyper-navigate}`Netflix Tutorial <search-tutorial-netflix>`
 
 
 :::
@@ -374,7 +374,7 @@ and how they can be customized to specific needs, using plugins for CrateDB.
 
 options
 analyzer
-Usage <usage>
+Tutorial <tutorial>
 :::
 
 

docs/feature/search/fts/usage.md → docs/feature/search/fts/tutorial.md

@@ -4,7 +4,10 @@
 
 # Full-Text: Exploring the Netflix Catalog
 
-In this usage guide, we will explore how to manage a dataset of Netflix titles,
+:::{include} /_include/links.md
+:::
+
+In this tutorial, we will explore how to manage a dataset of Netflix titles,
 making use of CrateDB Cloud's full-text search capabilities.
 Each entry in our imaginary dataset will have the following attributes:
 
@@ -26,6 +29,12 @@ To begin, let's create the schema for this dataset.
 
 ## Creating the Table
 
+:::{div}
+The fastest and easiest way to get started with CrateDB is by deploying a
+free tier (CRFREE) cluster on [CrateDB Cloud][CrateDB Cloud Console]. Otherwise,
+see the {ref}`install` section to run CrateDB yourself.
+:::
+
 CrateDB uses SQL, the most popular query language for database management. To
 store the data, create a table with columns tailored to the
 dataset using the `CREATE TABLE` command.

docs/handbook/index.md

@@ -1,17 +1,15 @@
-(guides)=
-(howtos)=
-(tutorials)=
-(use-more-tutorials)=
+(handbook)=
 
 # Handbook
 
-Guides and tutorials about how to use CrateDB and CrateDB Cloud in practice.
+:::{div} sd-text-muted
+About using CrateDB and CrateDB Cloud in practice.
+:::
 
 
 ::::{grid} 4
 :padding: 0
 
-
 :::{grid-item-card} Getting Started
 :link: getting-started
 :link-type: ref
@@ -21,11 +19,9 @@ Guides and tutorials about how to use CrateDB and CrateDB Cloud in practice.
 :class-card: sd-pt-3
 :class-body: sd-fs-1
 :class-title: sd-fs-5
-
 {material-outlined}`rocket_launch;1.3em`
 :::
 
-
 :::{grid-item-card} Installation
 :link: install
 :link-type: ref
@@ -35,10 +31,54 @@ Guides and tutorials about how to use CrateDB and CrateDB Cloud in practice.
 :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} Connect
+:link: connect
+:link-type: ref
+:link-alt: Connecting to CrateDB
+:padding: 1
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+{material-outlined}`settings_input_svideo;1.3em`
+:::
+
+::::
+
+
+## Learn
+
+How-to guides, tutorials, and explanations.
+
+::::{grid} 4
+:padding: 0
+
+:::{grid-item-card} How-to guides
+:link: howtos
+:link-type: ref
+:link-alt: How-to guides about CrateDB
+:padding: 1
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+{material-outlined}`assistant_direction;1.3em`
+:::
+
+:::{grid-item-card} Tutorials
+:link: tutorials
+:link-type: ref
+:link-alt: Tutorials about CrateDB
+:padding: 1
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-5
+{material-outlined}`school;1.3em`
+:::
 
 :::{grid-item-card} Administration
 :link: administration
@@ -49,25 +89,21 @@ Guides and tutorials about how to use CrateDB and CrateDB Cloud in practice.
 :class-card: sd-pt-3
 :class-body: sd-fs-1
 :class-title: sd-fs-5
-
-{material-outlined}`auto_stories;1.3em`
+{material-outlined}`manage_accounts;1.3em`
 :::
 
-
-:::{grid-item-card} Performance Guides
+:::{grid-item-card} Performance guides
 :link: performance
 :link-type: ref
-:link-alt: CrateDB Performance Guides
+:link-alt: CrateDB Performance guides
 :padding: 1
 :text-align: center
 :class-card: sd-pt-3
 :class-body: sd-fs-1
 :class-title: sd-fs-5
-
 {material-outlined}`speed;1.3em`
 :::
 
-
 ::::
 
 
@@ -225,11 +261,13 @@ programming frameworks, software testing, time series data.
 
 ../install/index
 ../connect/index
+../howto/index
+../tutorial/index
+../admin/index
+../performance/index
 ../feature/index
 Ingestion <../ingest/index>
 ../topic/index
 Solutions <../solution/index>
 ../integrate/index
-../admin/index
-../performance/index
 ```

docs/howto/index.md

@@ -0,0 +1,76 @@
+(guides)=
+(howtos)=
+(howto-guides)=
+
+# How-to guides
+
+:::{div} sd-text-muted
+Instructions how to get tasks done with CrateDB.
+:::
+
+:::{rubric} 2025
+:::
+
+- {ref}`influxdb-usage`
+- {ref}`amqp-usage`
+- {ref}`mqtt-usage`
+- {ref}`mongodb-usage`
+- {ref}`mysql-usage`
+- {ref}`oracle-usage`
+- {ref}`postgresql-usage`
+- {ref}`telegraf-usage`
+- {ref}`statsd-usage`
+- {ref}`rsyslog-usage`
+- {ref}`opentelemetry-telegraf-usage`
+- {ref}`opentelemetry-otelcol-usage`
+- {ref}`iceberg-risingwave`
+
+:::{rubric} 2024
+:::
+
+- {ref}`arrow-import-parquet`
+- {ref}`kafka-connect`
+- {ref}`superset-usage`
+- {ref}`superset-sandbox`
+- {ref}`cluvio-usage`
+- {ref}`dapr-usage`
+- {ref}`An example with Datashader <datashader>`
+- {ref}`dask-usage`
+- {ref}`dbt-usage`
+- {ref}`Using JMeter with CrateDB <jmeter>`
+- {ref}`langchain-usage`
+- {ref}`metabase-usage`
+- {ref}`pandas-efficient-ingest`
+- {ref}`PyCaret and CrateDB <pycaret>`
+- {ref}`rill-usage`
+- {ref}`marquez-usage`
+
+:::{rubric} 2023
+:::
+
+- {ref}`Using DataGrip <datagrip>`
+- {ref}`Using DBeaver <dbeaver>`
+- {ref}`balena-usage`
+- {ref}`kestra-usage`
+- {ref}`nifi-usage`
+- {ref}`powerbi-desktop`
+- {ref}`powerbi-service`
+- {ref}`streamsets-usage`
+- {ref}`spark-usage`
+- {ref}`azure-databricks`
+- {ref}`prefect-usage`
+- {ref}`terraform-usage`
+- {ref}`trino-usage`
+
+:::{rubric} 2022
+:::
+
+- {ref}`prometheus-usage`
+
+
+:::{note}
+You can expect the more recent documents to be more up-to-date than previous
+ones. If you can discover any flaws, please report them back to us by
+navigating to the tool flyout in the top right corner of each page,
+then using "Suggest improvement" to leave your feedback.
+:::

docs/integrate/influxdb/usage.md

@@ -1,5 +1,5 @@
 (influxdb-usage)=
-# Import data from InfluxDB
+# Load data from InfluxDB
 
 In this quick usage guide, you will use the [CrateDB Toolkit InfluxDB I/O subsystem]
 to import data from [InfluxDB] into [CrateDB]. You can also import data directly

docs/integrate/locust/tutorial.md

@@ -479,7 +479,7 @@ If you want to download the locust data, you can do that on the last tab.
 When you want to run a load test against a CrateDB Cluster with multiple queries, Locust is a great and flexible tool that lets you quickly define a load test and see what numbers regarding users and RPS are possible for that particular setup.
 
 
-[CrateDB CLI tools]: https://cratedb.com/docs/crate/clients-tools/en/latest/connect/cli.html#cli
+[CrateDB CLI tools]: project:#cli
 [DBeaver]: https://dbeaver.io
 [fully-managed]: https://console.cratedb.cloud/
 [Locust]: https://locust.io

docs/topic/timeseries/learn/query.md

@@ -1,9 +1,13 @@
 (timeseries-analysis-advanced)=
 (timeseries-analysis-weather)=
 (timeseries-querying)=
+(timeseries-tutorial-weather)=
 
 # Analyzing Weather Data
 
+:::{include} /_include/links.md
+:::
+
 CrateDB is a powerful database designed to handle various use cases, one of
 which is managing time series data. Time series data refers to collections of
 data points recorded at specific intervals over time, like the hourly
@@ -50,6 +54,12 @@ readings from CrateDB offices across the globe. Each record includes:
 
 ## Creating the Table
 
+:::{div}
+The fastest and easiest way to get started with CrateDB is by deploying a
+free tier (CRFREE) cluster on [CrateDB Cloud][CrateDB Cloud Console]. Otherwise,
+see the {ref}`install` section to run CrateDB yourself.
+:::
+
 CrateDB uses SQL, the most popular query language for database management. To
 store the weather data, create a table with columns tailored to the
 dataset using the `CREATE TABLE` command:

docs/topic/timeseries/learn/with-metadata.md

@@ -1,8 +1,12 @@
 (timeseries-objects)=
 (timeseries-with-metadata)=
+(timeseries-tutorial-metadata)=
 
 # Analyzing Device Readings with Metadata Integration
 
+:::{include} /_include/links.md
+:::
+
 CrateDB is highly regarded as an optimal database solution for managing
 time series data thanks to its unique blend of features. It is particularly
 effective when you need to combine time series data with metadata, for
@@ -50,6 +54,12 @@ like manufacturer, model, and firmware version.
 
 ## Creating the Tables
 
+:::{div}
+The fastest and easiest way to get started with CrateDB is by deploying a
+free tier (CRFREE) cluster on [CrateDB Cloud][CrateDB Cloud Console]. Otherwise,
+see the {ref}`install` section to run CrateDB yourself.
+:::
+
 CrateDB uses SQL, the most popular query language for database management. To
 store the device readings and the device info data, define two tables with
 columns tailored to the datasets.
@@ -125,7 +135,7 @@ WITH (compression='gzip', empty_string_as_null=true)
 RETURN SUMMARY;
 :::
 
-## Time Series Analysis with Metadata
+## Analyzing Data
 
 
 :::{rubric} JOIN Operations