docs(platform): IA content-sharing decision — self-canonical + inline transclusion (#7233)#7301
Open
jstirnaman wants to merge 8 commits into
Open
docs(platform): IA content-sharing decision — self-canonical + inline transclusion (#7233)#7301jstirnaman wants to merge 8 commits into
jstirnaman wants to merge 8 commits into
Conversation
Move /platform/faq/ to the data-driven faq pattern: questions live in data/faqs/platform.yml, rendered by the faq shortcode and emitted as schema.org FAQPage JSON-LD via faq_data/faq_canonical frontmatter. Add four category-level Q&As (what InfluxDB is used for, which industries, when to use a time series database, is it open source), expand the relational-database comparison, and keep the decision-page cross-link. Add a Cypress spec asserting the visible Q&As, stable anchors, and the FAQPage JSON-LD shape. Closes #7202
Validate-first design for the Phase 2 IA content-sharing mechanism: a canonical-honoring test protocol (dual target: byte-identical release-notes with canonical vs. identical engine pages without) and an outcome-keyed decision rubric. Defers the route choice until data lands. Splits downstream work into #7297 (mechanism spike) and #7298 (pilot conversion). Refs #7230, #7232
Decide Route 2 (conventional split) + promote #7245 canonical cleanup to do-now, on field evidence and rubric structure rather than the gated hand-run audit. Repurpose the section-3 test as non-blocking before/after validation. Add field-evidence and reference-vs-usage sections.
…erence Scope the #7245 urgent pass to Core<->Enterprise shared content (canonical to Enterprise as the most complete edition). Defer canonical ownership for reference shared across all v3 editions (client libraries, etc.) to broader cross-edition IA work; keep current canonical in the meantime.
jstirnaman
changed the title
… transclusion Rewrite the IA content-sharing decision doc around canonical: self. Each edition stays self-canonical and shares content by inline transclusion, rather than consolidating shared pages to a sibling edition (which would route Core readers into Enterprise docs). - D1: transclude shared prose inline; cross-edition links only for upgrade suggestions, never to complete a page - D3: keep each edition self-canonical; fold reference-vs-usage classification in; #7245 becomes 'add canonical: self' - Tighten from 336 to ~140 lines, Google developer style
jstirnaman
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Records the IA content-sharing decision for the job-led docs IA: how engine and
reference content is shared across InfluxDB 3 Core, Enterprise, and the
deployment variants, and how to set
rel=canonicalso shared content doesn'tstrand readers in the wrong edition.
Adds one design doc —
docs/exec-plans/active/2026-06-03-ia-sharing-canonical-validation-design.md.No content or template changes. (The platform FAQ work that originally shared
this branch already landed via #7295, so the net diff here is the design doc
alone.)
Closes #7233 · Unblocks #7232 · Advances #7245
Decision
Each edition stays self-canonical; shared content is transcluded inline. A
Core reader stays in Core docs — search, AI, and internal links keep them there.
Sharing is handled by authoring shared prose once and rendering it in each
edition, not by pointing one edition's canonical at another.
The four decisions:
prose (no
show-in/hide-in) and transclude it into each edition. Each pageis complete at its own URL. Cross-edition links are allowed only to suggest an
upgrade, never to complete a page.
the original decision rubric argues against canonical work, and field evidence
shows canonical signals are honored at the index layer — so
canonical: selfreliably keeps each edition distinct. The measurement test can't change the
action, so it isn't a gate.
canonical. This folds in the reference-vs-usage classification.
the pilot pages (Phase 2 AI visibility: pilot content-sharing conversion (IA migration de-risk) #7298); never gates the migration.
What this changes for #7245
The urgent task flips. It is not "point shared pages at Enterprise" — that's
already the automatic behavior: a page with
source:and nocanonicalinherits a sibling edition's canonical (Enterprise first), so Core engine pages
already route to Enterprise today. The fix is to add
canonical: selfwhereit's missing, so Core readers stay in Core. One-line, reversible change.
Byte-identical reference shared across all five v3 editions (client libraries,
line protocol, SQL/InfluxQL) is a separate case where consolidating to one owner
may be worth it — deferred to the broader cross-edition IA work.
Reviewing
This is a design / decision record (an exec-plan), not rendered content — no
preview pages. Review the decision and its rationale. Start with D1 (the
mechanism and the
canonical: selfexample) and D3 (the canonical rule andthe #7245 re-scope).
The doc lives under
docs/exec-plans/active/and is intended to persist onmaster(thecleanup-ephemeral-docsworkflow scrubs onlyPLAN.md/HANDOVER.md, not this path).Checklist