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

Documentation updates to CrateDB solution pages, expanding narratives around analytics, machine learning, time-series processing, and industrial IoT capabilities. Includes restructured content emphasizing distributed architecture, native capabilities, and cross-solution relationships. Removes "Explanations" heading from main solution index.

Changes

Cohort / File(s)	Summary
Analytics & Time-Series Content Expansion docs/solution/analytics/index.md, docs/solution/time-series/index.md	Replaced concise descriptions with expanded narratives emphasizing real-time exploratory queries on complete raw datasets, horizontal scalability, native time-series handling, and billions-of-records querying capabilities.
Machine Learning & Industrial Integration docs/solution/machine-learning/index.md, docs/solution/industrial/index.md	Added substantial introductory content detailing AI/ML demands and CrateDB's platform positioning (embeddings, MLOps, ML integrations). Industrial page restructured with new Related section, expanded tags (Industry 4.0, SCADA, MDE), and Technologies section.
Solution Index & Cross-Reference Updates docs/solution/index.md, docs/solution/longterm/index.md	Added descriptive block under Solutions, removed Explanations heading. Added cross-reference anchor to longterm store. Establishes interconnections across solution domains.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Review cross-references and internal links between solution pages for consistency
• Verify factual accuracy of CrateDB capability claims (especially time-series, ML integrations, vector storage)
• Check that Related sections correctly reference updated page structure and content positioning

Possibly related PRs

• Solutions: Refurbish whole section #438 — Modifies and restructures the same docs/solution/* files with overlapping content/structure changes across analytics, machine-learning, time-series, industrial, and longterm pages
• Index and Topics: Improve guidance #369 — Makes overlapping changes to docs/solution/index.md by adding descriptive blocks under Solutions and use cases
• Machine learning: Rework and relocate section #314 — Directly modifies and expands docs/solution/machine-learning/index.md with ML solution page content

Suggested labels

guidance

Suggested reviewers

• seut
• matriv
• kneth

Poem

🐰 Our docs now bloom with narratives bright,
Real-time queries, ML insights in sight,
Time-series flows, industrial pride,
Cross-references guide the journey wide,
A unified story, solutions aligned! ✨

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" is directly and specifically related to the changeset. The raw summary shows that the changes across multiple files (analytics, machine-learning, industrial, longterm, and time-series) involve adding, expanding, or improving introductory narrative and explanatory content blocks. The title accurately captures the primary objective of these changes—enhancing the explanatory teaser texts in the Solutions section—without being vague or misleading. The title is concise, clear, and provides sufficient specificity for a reviewer to understand the main focus of the work.
Description Check	✅ Passed	The pull request description is clearly related to the changeset. It identifies the problem (missing or improvable teaser texts on specific sections), describes the solution (adding concise introductory/explanatory texts), and provides preview links, references, and detailed context about the changes. The description accurately reflects the modifications shown in the raw summary, including the addition of expanded narrative content to time-series, analytics, and machine-learning documentation pages. The disclaimer about LLM-assisted content generation and the instructions provided add transparency and relevance to the changeset.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch solution-explanation

---

📜 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 bb1ad9e and b9037e7.

📒 Files selected for processing (6)

• docs/solution/analytics/index.md (2 hunks)
• docs/solution/index.md (1 hunks)
• docs/solution/industrial/index.md (1 hunks)
• docs/solution/longterm/index.md (1 hunks)
• docs/solution/machine-learning/index.md (1 hunks)
• docs/solution/time-series/index.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/solution/industrial/index.md
• docs/solution/longterm/index.md

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-08-23T15:15:18.717Z

Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/ai-integration.md:265-273
Timestamp: 2025-08-23T15:15:18.717Z
Learning: In CrateDB documentation, avoid using "data lake" terminology when describing CrateDB's role, as it can create misconceptions. Prefer "real-time analytics store" or similar terms that better reflect CrateDB's actual capabilities as a real-time analytics database.

Applied to files:

• docs/solution/analytics/index.md
• docs/solution/time-series/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

🔇 Additional comments (5)

docs/solution/index.md (2)

6-10: High-level teaser text provides clear CrateDB positioning.

The added muted div (lines 6-10) effectively summarizes CrateDB's core value proposition—distributed scalability, near real-time analytics, PostgreSQL compatibility, and Lucene foundation. This serves well as an entry point for the Solutions section.

---

21-75: Note: Inconsistency between AI summary and provided code.

The AI-generated summary states that the "Explanations" heading (line 21) was removed from this page, but the provided code still shows this heading without a change marker (~). Per the code-review instructions, removed lines should not appear in the provided code.

Please verify whether the "Explanations" heading was intentionally retained, or if the summary is reporting a change not fully reflected in the provided context.

docs/solution/machine-learning/index.md (1)

14-37: Well-articulated ML narrative emphasizing unified platform and practical integrations.

The four-paragraph introduction effectively positions CrateDB as a unified platform for modern AI/ML workflows. The progression from domain challenges (efficient vector storage, ML framework integration, model artifact management) through CrateDB's capabilities (native FLOAT_VECTOR, HNSW, LangChain/LlamaIndex, MLflow/PyCaret) to tangible benefits (avoiding specialized systems fragmentation) is logical and compelling.

Technical details are accurate and integrations are well-chosen. The conclusion appropriately reinforces PostgreSQL compatibility and standard database interfaces, maintaining consistency with other solution pages.

docs/solution/time-series/index.md (1)

8-31: Robust time-series narrative grounding domain challenges and positioning CrateDB's native capabilities.

The four-paragraph introduction clearly articulates the time-series domain—high write throughput, variable time-range queries, downsampling/retention trade-offs, and the operational fragmentation of traditional multi-system approaches. CrateDB's positioning as a native, single platform is well-supported: distributed architecture, partitioning for lifecycle management, and built-in functions for downsampling and time-window operations.

The narrative avoids imprecise framing (e.g., "data lake"), maintains active voice, and concludes with the PostgreSQL compatibility statement consistent across solution pages. Domain examples (IoT, sensors, financial transactions) ground the challenge authentically.

docs/solution/analytics/index.md (1)

8-27: Analytics narrative effectively frames the accessibility-retention trade-off and CrateDB's resolution.

The three-paragraph introduction clearly articulates the core tension in analytics—choosing between real-time query capability and long-term data retention. CrateDB's positioning as a unified hot-zone system (no downsampling, billions of records, full-dataset query performance) is compelling and differentiated.

The second paragraph's contrast with traditional approaches (pre-aggregated rollups, loss of granularity, limited ad-hoc analysis) is well-reasoned. The emphasis on "near real-time exploratory queries" is appropriately measured. The third paragraph articulates tangible operational benefits (avoiding hot/cold tiers, ETL overhead, data movement), grounding the value proposition in infrastructure simplification.

The minor reordering in the Related section (lines 45, 47) appropriately emphasizes time-series and longterm-store connections, reflecting the analytical workflow.

---

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

[matriv]

Looks good, thank you.
Posted a few minor suggestions.