Skip to content

Decide: should docs link AI assistants directly (Open in ChatGPT / Open in Claude)? #1236

Description

@ericgregory

#1233 contributes a copy-page dropdown for the v2 docs with four items: Copy page, View as Markdown, Open in ChatGPT, and Open in Claude. Per review, we're landing the first two now and splitting the assistant links into this decision, so it's made deliberately rather than by merge.

The question: Should the docs link users directly to specific commercial AI assistants, and if so, under what inclusion policy?

Considerations:

  • No CNCF project ships assistant links in its docs today. A code search across ten major orgs (kubernetes, open-telemetry, dapr, argoproj, backstage, cilium, envoyproxy, istio, helm, prometheus) found zero implementations. Merging them would make wasmCloud a first mover.
  • OpenTelemetry chose the neutral subset of this feature. opentelemetry.io#8146 requests copy-as-Markdown explicitly for pasting into assistants; maintainers pushed the feature upstream to google/docsy — copy/view Markdown, no vendor links.
  • CNCF vendor-neutrality guidance (contribute.cncf.io): project communications "should not favor one vendor's solution over another"; "one company should not be favored over any other companies offering the same services"; vendor-integration surfaces should have documented, objective inclusion criteria.
  • Neutral AI affordances are the current CNCF norm: llms.txt is live on opentelemetry.io, dapr.io, and wasmcloud.com; CNCF has also partnered with kapa.ai to offer projects hosted docs assistants.

Options:

  1. Don't add assistant links. Copy/View Markdown + llms.txt serve the same need neutrally. Matches current CNCF practice.
  2. Add them with a published inclusion policy. The guidance's own pattern for vendor listings: documented, objective criteria (e.g., "any generally available assistant with a public URL-prefill endpoint; additions welcome by PR"), applied consistently. Accepts first-mover status knowingly and takes on maintaining the list (Gemini, Copilot, etc. requests should be expected).
  3. Explore the CNCF kapa.ai program instead: an Ask-AI widget grounded in our docs (plus a hosted MCP endpoint and docs-gap analytics), provided at the foundation level. Complementary to option 1 rather than exclusive.

The contributor's implementation from #1233 is ready to restore if option 2 is chosen.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions