Solutions: Add or improve narrative explanation texts

[amotl]

Problem

Teaser texts have been missing or can be improved on the "time series", "analytics", and "machine learning" sections.

Solution

The patch supports recent refurbishments by adding concise introductional/explanatory teaser texts which are covering the ingredients of corresponding sections optimally.

Preview

• https://cratedb-guide--441.org.readthedocs.build/solution/time-series/
• https://cratedb-guide--441.org.readthedocs.build/solution/analytics/
• https://cratedb-guide--441.org.readthedocs.build/solution/machine-learning/

References

• Solutions: Refurbish whole section #438
• Improve general guidance aka. easy user journey #227

Disclaimer / Review

Please note this patch includes content generated by one or multiple LLMs, in this case using CodeRabbit AI. However, its use has been guided under very narrow constraints, applied just on certain spots, in a bottom-up fashion ¹, mostly used as a text summarizer, and instructed to avoid any yapping. We think the outcome is reasonable, but please don't hesitate to share your honest opinion.

The instructions to generate those text fragments have been:

:::{todo}
**Instructions:**
Elaborate a bit longer about the topic domain and the ingredients of this section
in an abstract way, concisely highlighting and summarizing relevant benefits,
like the `../analytics/index`, `../industrial/index`, and `../longterm/index`
pages are doing it already.
Use concise language, active voice, and avoid yapping.
:::

If you are interested in how this process works, please have a look at the resolved conversations below, and the accompanying commit 54b2c19.

Footnotes

1. First, write the unique content within subsections intellectually, then it's fine to use an advanced text summarizer for compressing the gist, when needed. Going the other "top-down" way, creating whole pages or sections using LLM technologies without much guidance will provide a doomed approach on many levels. We've already seen it happening, so we wanted to exercise a different approach hereby. ↩

[coderabbitai]

Walkthrough

Expanded and reorganized several solution docs: analytics, machine-learning, time-series, industrial, and solution index. Added detailed narrative content, new related links/tags/technologies, and four anchor identifiers for longterm; no code or API changes.

Changes

Cohort / File(s)	Summary
Solutions — expanded narratives docs/solution/analytics/index.md, docs/solution/time-series/index.md, docs/solution/machine-learning/index.md, docs/solution/industrial/index.md, docs/solution/index.md	Replaced brief descriptions with expanded, reformulated content covering real-time analytics, time-series handling, ML/vector workflows, and industrial use cases; adjusted related-links, tags, technologies, and reordered toctree entries.
Longterm anchors docs/solution/longterm/index.md	Added four cross-reference anchors: (longterm)=, (longterm-store)=, (timeseries-longterm)=, (timeseries-long-term-storage)= (no content changes).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Mixed-content changes across multiple documentation pages (new long-form content and structural/toctree edits).
• Pay extra attention to:
  • docs/solution/index.md (toctree changes and removed heading)
  • docs/solution/machine-learning/index.md (new integrations and vector/ML claims)
  • docs/solution/analytics/index.md and docs/solution/time-series/index.md (claims about storage tiers, downsampling, and scalability)
  • Cross-reference anchors in docs/solution/longterm/index.md

Possibly related PRs

• Solutions: Refurbish whole section #438 — Modifies and restructures the same solutions area, overlapping analytics/time-series/machine-learning edits.
• Machine learning: Rework and relocate section #314 — Reworks machine-learning solution page and related content; likely to overlap with ML additions here.
• Index and Topics: Improve guidance #369 — Adjusts Solutions content/toctree and presentation for docs/solution/index.md; related to the index changes.

Suggested labels

guidance

Suggested reviewers

• matriv
• seut
• bmunkholm

Poem

🐰 In docs I hop and nibble lore,
New pages bloom across the floor.
Analytics, time, and ML too,
Anchors placed and links made new.
A joyful hop — the guide says "woo!" 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Solutions: Add or improve narrative explanation texts" directly and accurately reflects the main objective of the changeset. The PR systematically expands explanatory content across multiple solution pages—time-series, analytics, and machine-learning—replacing concise descriptions with detailed narratives that explain CrateDB's capabilities for each use case. The title is concise (7 words, 53 characters), clear, specific enough to convey the primary change without unnecessary verbosity, and contains no vague terms, emojis, or extraneous noise. A teammate reviewing commit history would immediately understand that this PR improves and expands narrative explanations across the Solutions section.
Description Check	✅ Passed	The PR description clearly and directly relates to the changeset. It identifies the problem (missing or improvable teaser texts in specific sections), describes the solution (adding concise introductory/explanatory teaser texts), and this is directly confirmed by the raw summary showing expanded explanatory content added to the time-series, analytics, and machine-learning sections. The description is not vague or generic—it provides specific problem/solution framing, preview links, GitHub references, and detailed context about the LLM-assisted approach with specific instructions used. The description accurately corresponds to the actual changes made across the affected documentation files.

✨ 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 solution-explanation

---

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