Diátaxis: Index how-to guides and tutorials #364
Conversation
WalkthroughDocumentation updates across multiple sections: added links include, introduced new tutorial and how-to index pages, renamed “Usage” to “Tutorial” in several toctrees, added promotional blocks for CrateDB Cloud free tier, adjusted intros and section titles, and updated a header in the InfluxDB integration page. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
amotl
changed the title
amotl
added
cross linking
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
amotl
force-pushed
the
howto-guides-tutorials
branch
from
637b088 to
42d887e
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/topic/timeseries/learn/with-metadata.md (1)
145-151: Fix schema names in SQL examplesTables are created under the
docschema, but several queries switch todevices.*or omit the schema entirely. Running these snippets as-is will error out for readers following the tutorial. Please align the examples with the defined table names.SELECT * -FROM devices.readings r -JOIN devices.info i ON r.device_id = i.device_id +FROM doc.devices_readings r +JOIN doc.devices_info i ON r.device_id = i.device_id LIMIT 30;FROM - devices_readings r + doc.devices_readings r JOIN - devices_info i ON r.device_id = i.device_id + doc.devices_info i ON r.device_id = i.device_id-FROM - devices_readings r, max_timestamp m +FROM + doc.devices_readings r, max_timestamp m … -FROM - devices_info +FROM + doc.devices_infoAlso applies to: 195-212, 244-285
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
docs/_include/links.md(1 hunks)docs/feature/document/index.md(1 hunks)docs/feature/document/tutorial.md(3 hunks)docs/feature/search/fts/index.md(2 hunks)docs/feature/search/fts/tutorial.md(2 hunks)docs/handbook/index.md(2 hunks)docs/howto/index.md(1 hunks)docs/integrate/influxdb/usage.md(1 hunks)docs/topic/timeseries/learn/query.md(2 hunks)docs/topic/timeseries/learn/with-metadata.md(3 hunks)docs/tutorial/index.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/integrate/influxdb/usage.md
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/_include/links.md
- docs/howto/index.md
- docs/feature/search/fts/tutorial.md
- docs/topic/timeseries/learn/query.md
🧰 Additional context used
🧠 Learnings (5)
📓 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-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/feature/document/tutorial.mddocs/topic/timeseries/learn/with-metadata.md
📚 Learning: 2025-08-09T11:00:03.578Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.
Applied to files:
docs/feature/document/tutorial.mddocs/topic/timeseries/learn/with-metadata.md
📚 Learning: 2025-08-23T04:22:52.597Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/going-further.md:20-38
Timestamp: 2025-08-23T04:22:52.597Z
Learning: In the CrateDB Guide repository, the prefix `crate-reference:` in documentation links (like `crate-reference:index`) is an intersphinx reference that points to external content in the CrateDB Reference Manual documentation. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/topic/timeseries/learn/with-metadata.md
📚 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/tutorial/index.md
🪛 markdownlint-cli2 (0.18.1)
docs/topic/timeseries/learn/with-metadata.md
59-59: Reference links and images should use a label that is defined
Missing link or image reference definition: "cratedb cloud console"
(MD052, reference-links-images)
docs/tutorial/index.md
50-50: 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
| :::{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 about to run CrateDB yourself. |
There was a problem hiding this comment.
Polish the installation sentence
Same wording nit here—please change “see the … section about to run CrateDB yourself” to “see the … section to run CrateDB yourself.”
🤖 Prompt for AI Agents
In docs/feature/document/tutorial.md around lines 35 to 38, fix the wording in
the installation sentence: replace “see the {ref}`install` section about to run
CrateDB yourself” with “see the {ref}`install` section to run CrateDB yourself”
so the sentence reads fluently; update the text accordingly without altering
other surrounding content or formatting.
| 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 about to run CrateDB yourself. |
There was a problem hiding this comment.
Tighten the installation sentence
“see the … section about to run CrateDB yourself” reads awkwardly. Suggest rephrasing to “see the … section to run CrateDB yourself.”
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
59-59: Reference links and images should use a label that is defined
Missing link or image reference definition: "cratedb cloud console"
(MD052, reference-links-images)
🤖 Prompt for AI Agents
In docs/topic/timeseries/learn/with-metadata.md around lines 58 to 60, the
sentence "see the {ref}`install` section about to run CrateDB yourself" is
awkward; change it to "see the {ref}`install` section to run CrateDB yourself."
Update the phrasing only (remove "about") and ensure punctuation/spacing remains
correct and the reference link syntax stays intact.
| :::{card} | ||
| :width: 50% | ||
| :link: https://learn.cratedb.com/ | ||
| :link-alt: The CrateDB Academy | ||
| :class-header: sd-text-center sd-fs-5 sd-align-minor-center sd-font-weight-bold sd-text-capitalize | ||
| :class-body: sd-text-center sd-fs-5 | ||
| :class-footer: text-smaller | ||
| Academy Courses |
There was a problem hiding this comment.
Resolve the MD034 bare‑URL lint warning
markdownlint flags the :link: https://learn.cratedb.com/ attribute as a bare URL. Please convert it to use a named reference (e.g., define [CrateDB Academy]: https://learn.cratedb.com/ in /_include/links.md and change the card to :link: CrateDB Academy with the matching :link-type:) so the docs build passes.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
50-50: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/tutorial/index.md around lines 48 to 55, the card uses a bare URL in the
:link: attribute which triggers MD034; replace the bare URL with a named
reference (change :link: https://learn.cratedb.com/ to :link: CrateDB Academy
and add :link-type: reference on the card), and add a corresponding link
definition in /_include/links.md such as a single-line entry mapping "CrateDB
Academy" to https://learn.cratedb.com/ so the markdownlint warning is resolved.
About
After phasing out the crate-howtos and crate-tutorials repositories, and re-integrating content here, let's use ideas from Diátaxis to group and index 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
References