Diátaxis: Index how-to guides and tutorials

[amotl]

About

After phasing out the crate-howtos and crate-tutorials repositories, and re-integrating content here, let's use ideas from Diátaxis to loosely start grouping/indexing relevant content again.

Remark: Not many articles enumerated at Overview of CrateDB integration tutorials are actually tutorials per Diátaxis "tutorials" definition, so we slotted most of them into the "how-to" section instead.

Preview

• https://cratedb-guide--364.org.readthedocs.build/handbook/#learn
• https://cratedb-guide--364.org.readthedocs.build/howto/
• https://cratedb-guide--364.org.readthedocs.build/tutorial/

References

• Navigation: Rework categorization / grouping / TOC #10
• Merge Cloud Tutorials with new Guides section cloud-docs#68
• Consolidate Integration Guides I vs. II #102
• Improve general guidance aka. easy user journey #227
• Diátaxis - a systematic approach to technical documentation authoring #335

[coderabbitai]

Walkthrough

Documentation-only updates: added a shared links include and a CrateDB Cloud Console link, introduced/updated tutorial and how‑to index pages and handbook navigation, renamed several toctree labels from “Usage” to “Tutorial”, inserted promotional Cloud free‑tier blocks and minor header/section text changes; no runtime or code behavior changes.

Changes

Cohort / File(s)	Summary of changes
Shared links include docs/_include/links.md	Added a new link entry: CrateDB Cloud Console (https://console.cratedb.cloud/).
Document feature (Objects) docs/feature/document/index.md, docs/feature/document/tutorial.md	Renamed toctree labels from “Usage” → “Tutorial”; added include to /_include/links.md; added promotional/quick‑start blocks and reframed wording to “tutorial.”
Full‑text search (FTS) docs/feature/search/fts/index.md, docs/feature/search/fts/tutorial.md	Switched anchor/toctree targets to tutorial names; added /_include/links.md include and a Cloud free‑tier promotional block; wrapped sections with marketing framing.
Time series topics docs/topic/timeseries/learn/query.md, docs/topic/timeseries/learn/with-metadata.md	Inserted include /_include/links.md; added Cloud free‑tier promo blocks; added a topic alias (timeseries-tutorial-metadata); renamed a section to “Analyzing Data” and adjusted related narrative.
Tutorials & How‑to indexes docs/tutorial/index.md, docs/howto/index.md	Added new docs/tutorial/index.md and docs/howto/index.md with tutorial cards, Academy card, categorized rubrics, and feedback guidance.
Handbook navigation docs/handbook/index.md	Consolidated navigation entries into a single handbook group; added howto/index and tutorial/index to the toctree; small content addition under “All features.”
InfluxDB integration header docs/integrate/influxdb/usage.md	Changed main header from “Import data from InfluxDB” to “Load data from InfluxDB” (textual only).
Locust tutorial links docs/integrate/locust/tutorial.md	Replaced an external CLI link with an internal project reference and added three new markdown link references (nodeIngestBench, TimeIt, tutorial).

Sequence Diagram(s)

(No sequence diagrams included — changes are documentation/content-only and do not modify runtime control flow.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ETL/CDC: Guidance, Layout / Dissolve walls of links #239 — modifies docs/_include/links.md; closely related changes to shared link entries.
• Getting started: Rework whole section #232 — also updates docs/_include/links.md (Cloud and link definitions).
• Move "Getting started" to the root of the TOC #348 — related edits to docs/handbook/index.md and navigation/toctree structure.

Suggested labels

new content

Suggested reviewers

• bmunkholm
• kneth

Poem

I hop through docs with whiskers bright,
Adding links that guide the light.
Tutorials bloom where usage grew,
A cloud console link — fresh and new.
Hoppity hop, the docs feel right. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly and succinctly conveys the primary change of applying Diátaxis principles to index how-to guides and tutorials, and it directly reflects the content of the pull request without extraneous detail.
Description Check	✅ Passed	The description clearly explains the rationale for reintegrating content, the use of Diátaxis methods to organize how-to guides and tutorials, references to phased-out repositories, and includes preview links and relevant issue references, all of which are directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch howto-guides-tutorials

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f3d13f8 and d37fab0.

📒 Files selected for processing (1)

• docs/handbook/index.md (4 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: bmunkholm
PR: crate/cratedb-guide#340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

📚 Learning: 2025-10-06T16:40:16.322Z

Learnt from: amotl
PR: crate/cratedb-guide#0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Applied to files:

• docs/handbook/index.md

📚 Learning: 2025-09-25T19:31:54.320Z

Learnt from: bmunkholm
PR: crate/cratedb-guide#340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Applied to files:

• docs/handbook/index.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}