docs: scaffold Best Practices section - #50
Conversation
Reserve a Best Practices section on the docs site, wired into nav + sidebar in both locales. Establishes the one-practice-per-page convention (title → one-line statement → Why → Do/Don't → See also) with an index hub grouped by Modeling / Querying / Agent integration, and one seed practice (stable-identity) as a template. Further practices are filled in over time.
First Agent-integration best practice: a worked example (en+zh) of letting an AI agent scope reads through the object graph on the quickstart-multidomain pack — discover -> entity/search -> cross-domain topology -> datasets -> get_metrics/get_logs — instead of hand-writing SPL/PromQL. Embeds the 90s demo video (OSS-hosted). Wires it into the Best Practices index + sidebar (en+zh). VitePress build passes with no dead links.
|
Issue Evaluation Category: Feasibility: feasible This is a well-structured approach to scaffolding best practices documentation. The one-practice-per-page convention with consistent structure (title → statement → Why → Do/Don't → See also) provides a clear template for contributors. Starting with Note: The nav/sidebar overlap with #48 (schema reference) is documented. Whichever PR merges second will need trivial conflict resolution. Recommendation: Proceed with implementation. The bilingual structure and clear convention will make it easy for the community to contribute additional practices over time. Automated evaluation by github-manager-bot |
1 participant
What
Scaffolds a Best Practices section on the docs site — the place is reserved and wired in; practices get filled in over time.
docs/{en,zh}/best-practices/— bilingual section with an index hub establishing the one-practice-per-page convention (title → one-line statement → Why → Do/Don't → See also).stable-identity(use stable, domain-scoped identity) — as a working template to copy. Cross-links existing guides; no new prose duplicated.Adding a practice later = drop a page in
best-practices/and link it from the index + sidebar.Note
The nav/sidebar edits in
config/en.ts+config/zh.tsoverlap with #48 (schema reference). Whichever merges second will need a trivial conflict resolution (both just add a section to the same arrays).Verification
pnpm -C docs buildclean — 0 dead links;best-practices/pages render in both locales; no{{ }}leakage.