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

Two documentation files are modified to introduce and integrate explanatory guides. A new docs/explain/index.md file is created with explanation term aliases and descriptive content. The handbook index is restructured with grid layout adjustments, navigation updates, a new Explanations section added to the hierarchy, toctree modifications, and a feature diagram replaced with textual content.

Changes

Cohort / File(s)	Summary
New Explanations Guide docs/explain/index.md	New documentation file introducing explanation term aliases ((explain)=, (explanation)=, (explanations)=) with styled descriptive text about CrateDB explanatory guides and a note on document currency with feedback path.
Handbook Navigation and Layout Restructuring docs/handbook/index.md	Grid layout columns adjusted from 2 2 4 4 to 2 2 3 3 in multiple sections; Learn section label updated from assistant_direction to integration_instructions; new Explanations grid-item-card added with lightbulb icon; feature diagram image removed and replaced with textual caption; toctree updated to include ../explain/index.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Diátaxis: Index how-to guides and tutorials #364: Modifies docs/handbook/index.md navigation and toctree structure.
• Index and Topics: Improve guidance #369: Reshapes handbook index layout and toctree organization related to content reorganization.
• Chore: Improve UI responsiveness, specifically for smaller screen sizes #426: Modifies handbook index grid layout and metadata, introducing Explanations card integration.

Suggested labels

new content, refactoring

Suggested reviewers

• surister
• kneth
• bmunkholm

Poem

🐰 Through guides and grids, a tale unfolds,
Explanations bright with wisdom's gold,
New pathways carved to help us see,
Connected concepts, clear and free! 💡✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "Diátaxis: Add 'Explanations' section" directly describes the main change in the changeset. The raw summary confirms that a new "Explanations" section was introduced in the documentation structure, with updates to both docs/explain/index.md and docs/handbook/index.md to incorporate this new section. The title is concise, clear, and specific about what was added without unnecessary noise or vague phrasing.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	The pull request description is clearly related to the changeset provided. The author describes introducing an "Explanations" section based on the Diátaxis framework and staging a new section to be populated with subsequent patches, which directly aligns with the changes shown in the raw summary: the addition of docs/explain/index.md with explanatory guide documentation and modifications to docs/handbook/index.md to add an Explanations section. The description includes relevant context about the Diátaxis framework concept, provides preview links for reviewers, and references related GitHub issues (GH-227, GH-335), demonstrating clear intent and connection to the implementation.

✨ 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 explain

---

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