Diátaxis: Add "Explanations" section

[amotl]

About

Diátaxis proposes the idea of explanatory guides. This patch introduces it by staging a new section to be populated with subsequent patches based on refactoring existing content and adding new one.

Preview

• https://cratedb-guide--431.org.readthedocs.build/explain/
• https://cratedb-guide--431.org.readthedocs.build/handbook/#learn

References

• Improve general guidance aka. easy user journey #227
• Diátaxis - a systematic approach to technical documentation authoring #335

[coderabbitai]

Walkthrough

Adds a new explanatory guide page and integrates it into the handbook: creates docs/explain/index.md with explanation aliases and guidance, and updates docs/handbook/index.md to add an "Explanations" card, adjust grid layout and labels, and include the new page in the table of contents.

Changes

Cohort / File(s)	Summary
New Explanations Guide docs/explain/index.md	New documentation introducing explanation aliases ((explain)=, (explanation)=, (explanations)=) and a descriptive "Explanations" section with guidance on document currency and feedback via the tool flyout.
Handbook Navigation & Layout docs/handbook/index.md	Adjusted grid column layout (from 2 2 4 4 → 2 2 3 3), updated label from assistant_direction to integration_instructions, added an "Explanations" grid-item card (lightbulb icon), replaced a feature diagram with a textual caption, and added ../explain/index to the toctree.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Diátaxis: Index how-to guides and tutorials #364 — touches docs/handbook/index.md navigation and toctree structure.
• Index and Topics: Improve guidance #369 — updates handbook index layout and adds Learn/Explanations entry.
• Chore: Improve UI responsiveness, specifically for smaller screen sizes #426 — modifies handbook grid layout and integrates an Explanations card.

Suggested labels

new content

Suggested reviewers

• surister
• kneth
• bmunkholm

Poem

🐰 I hopped through pages, bright and spry,

New lightbulb guides beneath the sky—
Explanations placed with gentle care,
So readers find clear paths to share. ✨

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 "Diátaxis: Add 'Explanations' section" directly corresponds to the main changes in the pull request. The raw summary confirms that a new Explanations section is being introduced through updates to docs/explain/index.md and docs/handbook/index.md, including new content, aliases, navigation links, and a new Explanations grid-item-card. The title is concise, specific, and clearly communicates the primary objective of the changeset.
Description Check	✅ Passed	The PR description is directly related to the changeset. It explains that the patch introduces a new "Explanations" section aligned with the Diátaxis framework's concept of explanatory guides, staging the section for subsequent patches. This matches the raw summary showing additions to docs/explain/index.md and updates to docs/handbook/index.md that introduce explanatory content and navigation. The description provides adequate context about the purpose and intent of the changes.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch explain

---

📜 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 34f3b88 and 882e9db.

📒 Files selected for processing (2)

• docs/explain/index.md (1 hunks)
• docs/handbook/index.md (5 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/explain/index.md

[style] ~1-~1: The words ‘explain’ and ‘explanation’ are quite similar. Consider replacing ‘explain’ with a different word.
Context: (explain)= (explanation)= (explanations)= # Exp...

(VERB_NOUN_SENT_LEVEL_REP)

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

docs/explain/index.md (2)

1-3: False positive: Static analysis hint about similar words is not applicable here.

The reference aliases (explain)=, (explanation)=, and (explanations)= are intentionally defined with similar names to support flexible referencing conventions across the documentation. This is idiomatic MyST/Sphinx practice and not a defect.

---

5-22: Well-structured explanatory guide introduction aligned with Diátaxis framework.

The content effectively introduces the Explanations section with clear purpose, descriptive text, and user feedback integration via the existing tooling. The note on document freshness and feedback pathway is helpful for users.

docs/handbook/index.md (5)

10-10: Grid layout adjustment from 4-column to 3-column is justified by expanded content.

The change from grid 2 2 4 4 to grid 2 2 3 3 redistributes cards at larger breakpoints, reducing from 4 to 3 columns per row. This accommodates the expanded Learn section (now 5 items: How-to, Tutorials, Explanations, Administration, Performance) while improving card spacing and visual balance across all sections.

Also applies to: 54-54, 121-121

---

66-66: Material icon change improves semantic clarity for "How-to guides" card.

The icon change from assistant_direction to integration_instructions better conveys procedural guidance. Verify the icon renders correctly in the preview build.

---

80-89: New Explanations card properly integrated into Learn section with appropriate icon and reference.

The card is well-positioned logically (between Tutorials and Administration) and follows the established grid-item-card pattern. The lightbulb icon effectively conveys the insight/understanding purpose of explanatory guides. Verify the link reference :link: explanations resolves to the MyST anchor defined in docs/explain/index.md.

---

168-170: Feature diagram removed in favor of text-only caption.

The feature diagram image (PNG from cratedb.com) is replaced with a simple text caption preceded by the +++ MyST separator. This simplifies the layout but removes visual engagement. Verify that this change aligns with design intentions and that the link to "all-features" reference provides sufficient context for users seeking the comprehensive feature overview.

---

261-261: Toctree entry for new Explanations section correctly placed in navigation flow.

The new ../explain/index entry is logically positioned after tutorials and before administration, aligning with the Learn section's conceptual grouping. Path and reference format are consistent with surrounding entries.

---

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