71 search results

[nils-pzr]

---

📚 Documentation preview 📚: https://plone-aurora--116.org.readthedocs.build/

[stevepiercy]

I started an editorial review, but aborted my effort after I realized that this is not a how-to guide. Its content is more of an explanation and feels better placed in the conceptual guides.

If there is how-to material, then it should be in a separate page, focusing on how to perform tasks, not explain how things work.

Please take a look at the Diátaxis framework https://diataxis.fr/ for a thorough explanation of four quadrants of technical documentation. Feel free to hit me up in Discord for discussion.

[nils-pzr]

Thanks for the review, @stevepiercy - you were right, it was an explanation wearing a how-to hat.

Changes since your review:

• Split per Diátaxis: conceptual-guides/search.md (how it works) and how-to-guides/customize-the-search.md (tasks only); the old page is gone.
• Applied all your inline suggestions, including the newsfragment wording and the {file} role.
• Verified the accessibility claims in the browser before adopting your wording - that surfaced a missing keyboard focus indicator on the result links, now fixed (plus pagination links).
• All code excerpts in the docs are now verbatim from the source files.