Skip to content

docs: improve alternative backend and client discoverability#1985

Open
axelray-dev wants to merge 2 commits into
pydantic:mainfrom
axelray-dev:axelray-dev/fix-logfire-484-alt-doc-search
Open

docs: improve alternative backend and client discoverability#1985
axelray-dev wants to merge 2 commits into
pydantic:mainfrom
axelray-dev:axelray-dev/fix-logfire-484-alt-doc-search

Conversation

@axelray-dev
Copy link
Copy Markdown

@axelray-dev axelray-dev commented Jun 1, 2026

Fixes #484

What changed

Three minimal docs-only edits to improve search discoverability for alternative backends and alternative clients:

  1. docs/how-to-guides/alternative-backends.md: Added a sentence after the intro paragraph mentioning searchable keywords ("self-hosted backend", "collector", "Jaeger", "Grafana Tempo", "OTLP-compatible server").

  2. docs/how-to-guides/alternative-clients.md: Added language examples after "first-class supported languages": Go, Ruby, OpenTelemetry SDK. (Node.js and Rust removed from examples since they have first-class SDKs per docs/languages.md.)

  3. docs/why.md: Replaced the vague "cross-language data integration and data export to any OpenTelemetry-compatible backend or proxy" with explicit links to the Alternative Clients and Alternative Backends pages, mentioning Node.js, Rust, Go, Jaeger, and Grafana Tempo.

Why this helps search/discoverability

The docs site uses Algolia search (alt-logfire-docs index). Users searching for "opentelemetry server", "self-hosted backend", "OTLP", "Jaeger", "collector", "Go", "Ruby", or "alternative clients" will now find these pages more easily because:

  • The new keywords appear in the page body text (which Algolia indexes)
  • The OpenTelemetry section in why.md now links directly to both pages, creating discoverable cross-references
  • The language examples in alternative-clients.md match common search queries

Checks run

make lint          # passed, 243 files already formatted
make format        # 243 files left unchanged

Skipped checks

  • No local MkDocs build (docs are rendered by the pydantic/unified-docs pipeline, not locally).
  • No code changes. This is docs-only, so no tests were needed.

Fixes pydantic#484

- alternative-backends.md: add keywords for search indexing
  (self-hosted backend, collector, Jaeger, Grafana Tempo, OTLP-compatible server)
- alternative-clients.md: add language examples for search indexing
  (Node.js, Rust, Go, Ruby, OpenTelemetry SDK)
- why.md: replace vague 'cross-language data integration' with explicit
  links to Alternative Clients and Alternative Backends pages
@axelray-dev axelray-dev marked this pull request as ready for review June 1, 2026 14:13
@codecov
Copy link
Copy Markdown

codecov Bot commented Jun 1, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 3 files

Confidence score: 4/5

  • This PR is likely safe to merge with minimal risk because the reported issue is documentation-only and does not indicate runtime or functional regression.
  • The main concern is a user-facing docs inconsistency: docs/how-to-guides/alternative-clients.md says Node.js and Rust are outside first-class support, which conflicts with docs/languages.md and the page’s own SDK references.
  • Given the moderate severity (5/10) but high confidence (9/10), this is worth correcting soon to avoid reader confusion about supported languages.
  • Pay close attention to docs/how-to-guides/alternative-clients.md and docs/languages.md - ensure language support statements are consistent across docs.

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread docs/how-to-guides/alternative-clients.md Outdated
These languages have custom first-class SDKs per docs/languages.md.
Keep only Go, Ruby, and generic OpenTelemetry SDK languages as examples
of languages outside first-class support.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve search for alternative backends/clients

1 participant