Reorganize ADP nav around job-to-be-done workflows#38
Open
micheleRP wants to merge 2 commits into
Open
Conversation
Prototype draft that reframes the left-nav by user verbs (Connect data & tools, Monitor & debug, Control & govern, Routing & LLM settings) instead of feature nouns (Agents, MCP Servers, AI Gateway, Governance, Observability). Nav-only on top of main; no page-content edits and no file moves, so existing xrefs and URLs are preserved. Adds a top-level Quickstarts section (not in the prototype but critical to users) and folds the prototype's "Supported LLM providers" + "Quick start with one LLM" into one "Configure LLM provider" entry matching the charter wording. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Context
The current ADP nav (
modules/ROOT/nav.adoc, 132 lines) is organized by concept/noun: Agents, MCP Servers, AI Gateway, Governance, Observability, Integrations, Reference. The prototype reframes the IA by job-to-be-done verbs, with conversational labels that match how a customer would describe what they're trying to do, not what feature they're configuring.This PR rewrites
nav.adoconly — no file moves, no page-content edits — mapping the prototype's labels onto existing pages viaxref:[Label]overrides. The intent is to put the new shape in front of the team for review without committing to file moves yet.New shape (7 sections, 30 nav entries):
Preview nav
Prototype vs. charter workflows
Cross-checking the prototype's nav against the 11 charter workflows from the ADP GA Readiness Plan:
Cleanly matched (8 of 11)
Missing or partial in the prototype
mcp/create-server.adochas a home.Prototype also adds workflows not in the charter
These are mostly debugging/observability framings — reasonable IA, but worth flagging:
Major gaps (ordered by impact)
Gaps are nav slots in the prototype that have no existing page that fits cleanly:
transcripts.adocbut isn't extracted.agents/concepts.adocis loop-focused, not unified.permissions-overview.adoc. Splitting into a concept page + a how-to is the eventual fix.(The Settings reference gaps render as nav entries with no associated page in this PR — flagged for visibility, not yet wired up.)
Pages currently dropped from nav
These pages still exist on disk and are reachable by direct URL, but have no slot in the new shape. Most are subordinate flows that could become subsections of an existing workflow page in a follow-up:
agents/overview.adoc,agents/a2a-concepts.adoc,agents/system-prompts.adoc,agents/architecture-patterns.adoc,agents/integration-overview.adoc,agents/pipeline-integration-patterns.adoc,agents/monitor.adocagents/tutorials/*(customer-support-agent, transaction-dispute-resolution)mcp/oauth-providers.adoc,mcp/github-oauth-tutorial.adoc,mcp/test-tools.adocai-gateway/aggregation.adoc,ai-gateway/connect-agent.adoc,ai-gateway/admin/setup-guide.adoc,ai-gateway/builders/discover-gateways.adocgovernance/kill-switch.adoc(currently empty),governance/guardrails/cost-tracking.adoc(stub)observability/ingest-custom-traces.adoc,observability/logs.adocintegrations/{claude-code,cursor,continue,cline,copilot,remote-mcp-clients}.adocreference/pipeline-examples.adoc(empty stub)Open questions for the team
These are decision points baked into the current draft as assumptions; flag any you want changed:
mcp/test-tools.adocand that's about testing. Substituted "Build a tool server for your own data" somcp/create-server.adochas a home.byoa-register.adocis currently placed under Concepts ("Declarative vs. BYOA"); charter Update ADP docs for May 4 batch (rpk ai, Bedrock GA, governance V0) #11 (BYOA telemetry) gets a new slot under Monitor. Should BYOA register get its own how-to slot under Connect?permissions-overview.adoc. Acceptable as a duplicate xref for the preview, or split into two pages?🤖 Generated with Claude Code