Sharding and partitioning 101: Relocate to "performance guides" section

[amotl]

About

Also just a little reorganization/refactoring to shuffle pages around, like GH-466.

The content of this page is a bit in a limbo, but it is certainly a guide, and only uses SQL, so it is, when compared to other content in /admin, actually less about "admin" details than others.

[coderabbitai]

Walkthrough

Documentation restructuring moves sharding-partitioning reference from admin to performance index, adds guidance blocks about clustering and shard allocation best practices, and renames sharding documentation heading to emphasize recommendations.

Changes

Cohort / File(s)	Summary
Admin Documentation Index docs/admin/index.md	Removed toctree entry for sharding-partitioning under Cluster section; added new prose block with best practices guidance for clustering, sharding, and partitioning.
Performance Documentation Index docs/performance/index.md	Expanded sharding toctree from single entry to include both "sharding-partitioning" and "sharding"; added guidance card with shard allocation, ingestion performance, and storage capacity recommendations.
Sharding Documentation docs/performance/sharding.md	Renamed main heading from "Sharding performance guide" to "Sharding recommendations"; all other content unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Documentation-only changes with straightforward structural reorganization and text edits
• No code logic or complex dependencies to evaluate
• Verify consistency of terminology across moved/renamed sections

Possibly related PRs

• Layout: Curated index page for "Administration" and "Performance Guides" #265: Modifies the same admin and performance index files, replacing RST with Markdown and altering toctree entries for sharding-partitioning/sharding with explanatory content.
• Sharding strategy and recommendations #355: Updates sharding documentation files with overlapping changes to performance/sharding.md and related indices.
• Start/Index: Refactor "Going further" to "Learn more" on index page #368: Modifies docs/performance/index.md with overlapping changes to sharding toctree structure and shard allocation guidance.

Suggested labels

refactoring, guidance

Suggested reviewers

• kneth
• karynzv
• surister

Poem

🐰 Hop through docs, we organize with care,
Sharding guidance moved from here to there,
Best practices bloom on every page,
A cleaner structure for this documentation age!

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 PR title "Sharding and partitioning 101: Relocate to 'performance guides' section" directly and accurately summarizes the main change in the changeset. The raw summary confirms that the sharding-partitioning entry is being removed from the admin section (docs/admin/index.md) and added to the performance section (docs/performance/index.md), with accompanying documentation updates. The title is specific, clear, and concise, making it immediately apparent to someone reviewing the repository history what the primary change entails.
Description Check	✅ Passed	The PR description is related to the changeset and provides appropriate context for the reorganization. It explains that this is a reorganization/refactoring effort (similar to GH-466) and justifies the change by noting that the sharding and partitioning content is more of a guide that uses SQL and is less focused on administrative details compared to other content in the /admin section. This rationale directly supports the decision to move the content to the performance guides section as reflected in the file changes.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch relocate-sharding-guide

---

📜 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 d9ad151 and 8f85ac6.

📒 Files selected for processing (3)

• docs/admin/index.md (0 hunks)
• docs/performance/index.md (1 hunks)
• docs/performance/sharding.md (1 hunks)

💤 Files with no reviewable changes (1)

• docs/admin/index.md

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T13:45:25.891Z
Learning: For the cratedb-guide repository, general discussions and broader documentation concerns should be added to the existing runsheet/tracking ticket (e.g., GH-227) rather than creating separate issues.

⏰ 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 (3)

docs/performance/sharding.md (1)

4-4: Heading change aligns with reorganization.

The rename from "Sharding performance guide" to "Sharding recommendations" appropriately positions this content within the performance guides section as an advisory resource rather than procedural documentation.

docs/performance/index.md (2)

18-22: All toctree file references verified and exist.

Verification confirms that both sharding-partitioning.md and sharding.md exist in docs/performance/, along with scaling.md and storage.md. All toctree entries reference valid, existing files.

---

24-25: Guidance text is complete and accurate.

All four topics claimed in the guidance are confirmed present across the toctree entries:

• "Shard allocation" covered in sharding-partitioning.md and sharding.md
• "Optimizing ingestion performance" covered in sharding.md (Optimize for ingestion section)
• "Planning memory capacity" covered in scaling.md
• "Limits/recommendations related to storage" covered in storage.md

---

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