Improved getting started journeys

[bmunkholm]

About

• Moved "first steps" to the Getting Started page to get rid of another index layer of redirection.
• Added a "local" getting started section as a tab with the cloud variant to both provide local guidance while not having it disrupt the flow if it was on it's own page.
• Added an option to go through Academy instead for video led instructions.
• As consequence, collapsed the 2 options (cloud, install) on the Overview page to just direct to the new Getting Started page
• Made the 2 "new user" journeys more clear on the Overview page: Either you want to figure out if Crate is for you, or you are at the next steps where you want to try it. (later improvements could be to add an "About" page under Overview page targeted explaining "why" CrateDB.
• Added notes about CreateDB being OSS in Overview page.

Overall this should hopefully give a more smooth initial user journey.

Fixes https://github.com/crate/tech-content/issues/178 and https://github.com/crate/tech-content/issues/173

Preview

https://cratedb-guide--502.org.readthedocs.build/

[coderabbitai]

Walkthrough

Bumps the docs build version and applies broad documentation updates: rewrites the homepage, restructures the getting-started flow with Cloud/Local tabs, deletes the first-steps guide, updates video learning content, and adjusts two UNNEST anchor links. All changes are documentation-only.

Changes

Cohort / File(s)	Summary
Version docs/build.json	Bumped docs build version from 2.1.4 to 2.1.5.
Homepage docs/index.md	Full rewrite of homepage copy and layout: new open-source-focused intro, "Is CrateDB right for me?" and "New to CrateDB?" sections, updated quick-links grid/cards, CTAs, community & contribution guidance, and adjusted navigation targets.
Getting‑started / Start pages Start index & pages docs/start/index.md, docs/start/...	Reworked start/index with toctree and a Cloud (recommended) vs Local tabbed flow, promoted Academy, replaced tutorial tiles with new data-focused cards, refreshed "What's next?" content, updated CTAs and guidance.
Removed guide docs/start/first-steps.md	Deleted the entire onboarding/first-steps guide (file removed).
Video learning docs/start/video/index.md	Renamed/rewritten to "Video learning": added CrateDB Academy card, Featured Webinar with YouTube embed, updated playlists card and descriptive copy.
Anchor updates docs/feature/query/index.md	Updated two UNNEST anchor references to new anchored variants (#p-1195-unnest-5, #p-1521-ingesting-into-cratedb-with-unnest-3).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Review focus: docs/index.md and docs/start/index.md for toctree structure, tab content, CTAs, and internal link consistency.
• Verify deletion of docs/start/first-steps.md doesn't leave broken references elsewhere.
• Check media embed correctness in docs/start/video/index.md and updated anchors in docs/feature/query/index.md.

Possibly related PRs

• Reduce marketing msg in intro page and fix link to handbook. #424 — Overlapping homepage intro/navigation and quick-links/grid updates.
• Move "Getting started" to the root of the TOC #348 — Related top-level navigation and homepage restructuring.
• Getting started: Rework whole section #232 — Overlap on getting-started / start/index.md reorganization.

Suggested labels

enhancement, new content, guidance, reorganize, cross linking

Suggested reviewers

• kneth
• karynzv
• surister

Poem

🐰 I hopped through lines and nudged the start aside,
Tabs opened up, and videos now abide.
Cards rearranged, anchors found their place,
Version lifted up — the docs in brighter space.
Hop in, explore, and nibble at the trace.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: improving the user onboarding experience through restructured getting started journeys with clearer pathways.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description clearly relates to the changeset, detailing improvements to the getting started user journey including moving first steps content, adding local setup options, and restructuring overview navigation.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bm/improved-getting-started

---

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/start/index.md (1)

30-35: Clarify the phrase "more manual tutorials."

The text "Alternatively, select 'Local' below to install CrateDB with Docker and follow the more manual tutorials" is unclear about what "manual" means in this context. Does it mean less automated, less guided, or something else? Consider rewording for clarity, such as "follow the tutorial steps in the Admin UI" or "run tutorials locally step-by-step."

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 032fb36 and ac1906d.

📒 Files selected for processing (1)

• docs/start/index.md (1 hunks)

🧰 Additional context used

🧠 Learnings (11)

📓 Common learnings

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 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-09-25T19:31:54.320Z

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 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/start/index.md

📚 Learning: 2025-08-23T20:20:42.259Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 235
File: docs/start/going-further.md:20-27
Timestamp: 2025-08-23T20:20:42.259Z
Learning: In the CrateDB Guide documentation, use British English spelling "data modelling" rather than American English "data modeling".

Applied to files:

• docs/start/index.md

📚 Learning: 2025-10-30T23:12:30.204Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 465
File: docs/admin/troubleshooting/system-tables.md:6-6
Timestamp: 2025-10-30T23:12:30.204Z
Learning: In the cratedb-guide repository, documentation headers and titles should use sentence case (e.g., "Diagnostics with system tables") rather than title case (e.g., "Diagnostics with System Tables"). This style choice enables headers to be referenced more fluently within sentences.

Applied to files:

• docs/start/index.md

📚 Learning: 2025-10-20T21:49:18.785Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 406
File: docs/connect/go.md:110-137
Timestamp: 2025-10-20T21:49:18.785Z
Learning: In the cratedb-guide repository, documentation examples for connecting to CrateDB (e.g., Go examples in docs/connect/go.md) should be kept minimal and focused on demonstrating basic functionality, rather than including comprehensive error handling. Full examples with proper error handling are maintained separately in the cratedb-examples repository.

Applied to files:

• docs/start/index.md

📚 Learning: 2025-09-17T14:31:04.228Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-09-17T14:31:04.228Z
Learning: In Rill tutorial documentation for CrateDB integration, convert passive voice constructions like "will be directed", "can be done", "should open" to active voice alternatives such as "directs you", "enables", "opens" to create clearer, more direct instructions.

Applied to files:

• docs/start/index.md

📚 Learning: 2025-08-22T18:11:12.776Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 263
File: docs/integrate/kafka/docker-python.md:112-120
Timestamp: 2025-08-22T18:11:12.776Z
Learning: In documentation and tutorial repositories like cratedb-guide, code examples should prioritize simplicity, clarity, and educational value over production-ready features. Comprehensive error handling, extensive validation, and other production concerns can distract from the main learning objectives and make examples harder to follow. Review suggestions should focus on correctness and clarity rather than production hardening.

Applied to files:

• docs/start/index.md

📚 Learning: 2025-08-23T15:09:38.537Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.

Applied to files:

• docs/start/index.md

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

Learnt from: amotl
Repo: crate/cratedb-guide PR: 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/start/index.md

📚 Learning: 2025-09-22T22:05:05.734Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 279
File: docs/integrate/airflow/data-retention-hot-cold.md:14-14
Timestamp: 2025-09-22T22:05:05.734Z
Learning: When searching for labels in the CrateDB Guide documentation, remember that reStructuredText files (.rst) use the syntax `.. _label:` while MyST Markdown files (.md) use the syntax `(label)=`. Cross-references work between formats, so {ref}`label` in MyST can reference an RST label defined with `.. _label:`.

Applied to files:

• docs/start/index.md

📚 Learning: 2025-10-19T19:21:49.864Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.

Applied to files:

• docs/start/index.md

🪛 markdownlint-cli2 (0.18.1)

docs/start/index.md

190-190: Bare URL used

(MD034, no-bare-urls)

---

279-279: Bare URL used

(MD034, no-bare-urls)

---

289-289: Bare URL used

(MD034, no-bare-urls)

⏰ 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

🔇 Additional comments (5)

docs/start/index.md (5)

1-3: Consider sentence case for main page title.

The page title uses title case ("Getting Started"), but learnings from this repository indicate that headers should use sentence case (e.g., "Getting started"). Please verify whether this applies to main page titles, as this may be intentional for branding or consistency with other level-1 headings in the codebase.

---

5-14: Verify that all toctree references exist.

The toctree includes references to video/index, modelling/index, query/index, import, and application/index. Ensure these files exist and are correctly configured in the documentation structure, especially import (which appears to lack an /index path).

---

38-176: Excellent tabbed Cloud/Local onboarding flow.

The restructured Getting Started page delivers a clear, progressive learning path with a well-organized tab-set separating Cloud and Local options. Each path has a logical flow (setup → run tutorials → experiment), and the inclusion of figures/screenshots for each path enhances clarity. The tutorial cards (lines 140–163) are well-curated with distinct learning objectives.

---

136-165: Verify tutorial reference labels.

The tutorial cards reference the following labels: objects-tutorial-marketing, search-tutorial-netflix, timeseries-tutorial-weather, and timeseries-tutorial-metadata. Please confirm these reference targets exist in the corresponding tutorial documentation files in docs/start/ or elsewhere.

---

179-262: "What's next?" section is well-structured.

The reorganized "What's next?" section effectively guides users to the next steps with three clear categories (Continue learning, Start building, Community/Help). The grid-card layout is consistent, the reference links use correct MyST syntax (:ref: and :link-type: ref), and the accompanying icons reinforce each topic. As per learnings, ensure that all reference targets (data-modelling, query-capabilities, start-import, connect, example-applications) exist in the codebase.

[surister]

Read it all and I don't have any meaningful feedback other than it looks good. It's a 👍 from me.

[kneth]

The "Getting started" looks good now.