Wording: Tame use of "This section..."

[amotl]

About

"This section [...]" was used a bit too often across the board. This patch attempts to tame it.

[coderabbitai]

Walkthrough

Documentation-wide editorial updates: many introductory sentences were rephrased, several plain intros converted into muted/styled blocks, and the ingest/ETL page gained categorized grid/cards. No code, examples, commands, or public API declarations were changed.

Changes

Cohort / File(s)	Summary
Connect docs refresh docs/connect/application.md, docs/connect/drivers.md, docs/connect/general.md, docs/connect/java.md, docs/connect/javascript.md, docs/connect/php.md, docs/connect/python.md, docs/connect/ruby.md	Reworded lead sentences and converted several intros into muted/styled blocks; minor caption and phrasing tweaks; no changes to examples or functional content.
Ingest and ETL/CDC overview updates docs/ingest/index.md, docs/ingest/etl/index.md, docs/ingest/cdc/index.md	Inserted muted intros; added/renamed section headers and triple-plus blocks; ETL page gains categorized grid/cards and concise overview wording.
Install docs intros and wording docs/install/index.rst, docs/install/cloud/aws/index.rst, docs/install/container/index.rst, docs/install/container/kubernetes/kubernetes.rst, docs/install/tarball.rst	Reframed opening narratives into muted blocks, grammar/wording cleanups, and more generic section phrasing; no command or config changes.
Integrations docs updates docs/integrate/mcp/community.md, docs/integrate/mcp/cratedb-mcp.md, docs/integrate/prefect/usage.md	Replaced “This section/About …” with muted intro blocks; added short CrateDB MCP intro; Prefect lead sentence shortened; content otherwise unchanged.
Feature docs editorial tweaks docs/feature/storage/index.md, docs/feature/cursor/index.md, docs/feature/search/fts/analyzer.md	Storage intro and data-structure phrasing updated; cursor grammar fix; analyzer doc gains an info block and minor instruction wording changes.
Admin clustering note wording docs/admin/clustering/logical-replication-setup.md	Standardized note phrasing to “The following SQL statements are executed on …”; SQL examples unchanged.
Performance docs cleanup docs/performance/inserts/index.md, docs/performance/optimization.md	Minor sentence merges and rewording; several section intros wrapped in muted blocks and bullet phrasing adjusted.
Getting started minor edit docs/start/first-steps.md	Collapsed descriptive lines into a single sentence; no structural or example changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• MCP: Add first wave of material, mostly indexing existing others #204 — Overlaps MCP docs edits (docs/integrate/mcp/*); likely related to the same pages.
• Ingest: Add page about ingestion methods #230 — Related changes to the ingest index and ETL content (docs/ingest/*).
• Drivers: Fix broken links. Improve wording. #338 — Overlapping edits to drivers/connect docs (docs/connect/drivers.md).

Suggested labels

guidance

Suggested reviewers

• kneth
• surister

Poem

I thumped through pages, light and quick,
Muted blocks now shape each pick.
Cards aligned like rows of blooms,
Words rearranged in tidy rooms.
No code disturbed—just tidied tune—
Hop, hop, the docs hum gently soon.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly identifies the primary change as a wording update focused on taming the repeated phrase “This section…”, concisely summarizing the main intent of the pull request without extraneous details.
Description Check	✅ Passed	The description directly references the overuse of the phrase “This section…” and explains that the patch addresses it, making it relevant to the documented changes in the pull request.
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 rm-this-section

---

📜 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 22879c3 and 71ccdd9.

📒 Files selected for processing (1)

• docs/install/container/kubernetes/kubernetes.rst (3 hunks)

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

• docs/install/container/kubernetes/kubernetes.rst

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

docs/integrate/prefect/usage.md (1)

31-31: Restore a complete lead sentence.

The new wording reads as a sentence fragment and drops the subject that framed the walkthrough. Please keep the sentence complete for clarity.

-A simple workflow that fetches data, applies a basic transformation, and loads it into CrateDB.
+This example walks you through a simple workflow that fetches data, applies a basic transformation, and loads it into CrateDB.

docs/connect/application.md (1)

54-56: Tighten the lead-in sentence grammar

Consider rephrasing to “An overview of a few CLI programs, and how to use them for connecting to CrateDB clusters.” to avoid the awkward “overview about” construction while keeping the meaning intact.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 94dfc73 and 0c91f82.

📒 Files selected for processing (26)

• docs/admin/clustering/logical-replication-setup.md (2 hunks)
• docs/connect/application.md (1 hunks)
• docs/connect/drivers.md (2 hunks)
• docs/connect/general.md (1 hunks)
• docs/connect/java.md (1 hunks)
• docs/connect/javascript.md (1 hunks)
• docs/connect/php.md (1 hunks)
• docs/connect/python.md (1 hunks)
• docs/connect/ruby.md (1 hunks)
• docs/feature/cursor/index.md (1 hunks)
• docs/feature/search/fts/analyzer.md (2 hunks)
• docs/feature/storage/index.md (2 hunks)
• docs/ingest/cdc/index.md (1 hunks)
• docs/ingest/etl/index.md (1 hunks)
• docs/ingest/index.md (1 hunks)
• docs/install/cloud/aws/index.rst (1 hunks)
• docs/install/container/index.rst (2 hunks)
• docs/install/container/kubernetes/kubernetes.rst (3 hunks)
• docs/install/index.rst (1 hunks)
• docs/install/tarball.rst (1 hunks)
• docs/integrate/mcp/community.md (1 hunks)
• docs/integrate/mcp/cratedb-mcp.md (1 hunks)
• docs/integrate/prefect/usage.md (1 hunks)
• docs/performance/inserts/index.md (1 hunks)
• docs/performance/optimization.md (6 hunks)
• docs/start/first-steps.md (1 hunks)

🧰 Additional context used

🧠 Learnings (3)

📚 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/start/first-steps.md

📚 Learning: 2025-08-14T19:02:43.308Z

Learnt from: amotl
PR: crate/cratedb-guide#253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.

Applied to files:

• docs/connect/general.md

📚 Learning: 2025-08-05T07:14:57.416Z

Learnt from: hammerhead
PR: crate/cratedb-guide#221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.

Applied to files:

• docs/connect/java.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 (2)

docs/feature/cursor/index.md (1)

24-24: Nice cleanup on the wording.

Changing “same shape like” to “same shape as” improves the grammar without altering meaning.

docs/start/first-steps.md (1)

3-3: Reworded description reads smoothly

Updated phrasing is concise and aligns with the PR goal of toning down “This section…” wording. Good catch.

[bmunkholm]

Thanks!