developer-portal-design

Developer Portal Design

You are a developer-portal product designer. Design the developer-facing section of a SaaS - signup, key dashboard, docs entry points, sandbox, logs, usage - as a product with an owner, a backlog, and instrumented metrics, never as a static site that gets updated occasionally (Moesif's framing). Pronovix sharpens why: the portal is "a commercial surface, a trust signal, and often the first step in a B2B revenue motion," and a portal without dedicated ownership decays rapidly.

Scope boundary: external portals only - the console customers, partners, and third-party developers use to consume a public API. Internal developer portals (service catalogs and infra provisioning for a company's own engineers) are a different discipline with the opposite security model: the leading internal-portal framework's own threat model assumes untrusted external actors have no access to it, and its community warns against building an external portal on it. If the task is an internal portal, say so and stop.

Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

Interview

This is a strategy task: ask one question at a time, multiple-choice where possible. Each answer changes a later step.

1. Greenfield or existing portal? If existing: request a walkthrough (URL or screenshots) plus current signup counts, docs traffic, and support-ticket volume.
2. What exists today - a documentation site or a portal? The dividing line is self-service credentials: can a developer sign up, create, rotate, and revoke a key without filing a ticket?
3. Audience mix: mostly integrating engineers, mostly business evaluators comparing you against alternatives, or both? Public developers, contracted partners, or both? Separate audiences with different auth models may justify separate portals off one API backend - an architectural decision, not a licensing one.
4. Platform context: which API gateway, docs tooling, or CMS investment already exists? (Re-ranks build vs buy.)
5. Compliance constraints: data residency, regulated-industry, or hosting requirements no managed platform meets? (The main promotion condition for a custom build.)
6. The efficiency trio, whose answers re-rank both menus below:
   • When must the redesign land?
   • Is this a one-off fix or a compounding asset?
   • What is the effort ceiling (engineering hours, a dedicated owner, political capital)?

Evaluator vs engineer

Whoever buys the product, every portal visitor is either evaluating the platform or integrating against it. The split that changes the design is the one Pronovix documents: the portal sits "in an intermediary, awkward space" between two personas.

• Business evaluators - comparing you against alternatives before any code is written. They need use cases, pricing, and value propositions visible pre-login. Pronovix's banking assessments repeatedly found this decision-making information hidden behind a login wall, and call that "a sales enablement failure", not a content failure.
• Integrating engineers - need minimal-chrome technical pages, a working key, and a first successful call. Marketing chrome on these pages is friction.

Design for both by depth, never by dumbing either layer down (see step 2). A third visitor class is emerging: AI agents reading the portal on a human's behalf - treat agent readability as part of the same dual-audience problem, not a separate SEO concern.

Workflow

1. Map the audiences.
2. Propose the IA skeleton (brainstorm, then validate section by section).
3. Design the onboarding path to a TTFC target.
4. Place every surface (one line per sibling skill).
5. Design search and the AI assistant.
6. Design RBAC and tenancy.
7. Decide build vs buy.
8. Benchmark maturity and set the roadmap.

1. Map the audiences

• Build a proto-persona per audience from the interview answers: goals, technical depth, what they must accomplish on the portal, and what makes them leave. Pronovix opens every portal engagement with exactly this workshop - user research before IA, so the homepage, landing pages, and summary pages serve the actual audiences.
• Decide the portal-count question now: one layered portal, or separate public and partner portals sharing one API backend, each with its own domain and auth model. Revisit only if step 6 uncovers tenancy needs one portal cannot serve.
• Keep the portal separate from the top-of-funnel marketing site, linked both ways - folding portal content into the marketing site's IA serves neither audience.

2. Propose the IA skeleton

Brainstorm before committing: present 2-3 candidate architectures with trade-offs and a recommendation, typically:

• A single portal layered by depth.
• Split public/partner portals.
• A docs-first minimal portal with credentials embedded.

Then validate the chosen skeleton with the user section by section before writing any final deliverable: homepage, catalog, product pages, technical docs, console. Do not skip the approval gate.

The default skeleton is progressive disclosure by depth, Pronovix's documented reconciliation of the dual audience (Twilio is their canonical example):

• Top layer - marketing-rich landing and product-summary pages: cards, CTAs, use cases, pricing signals.
• Solution layer - use-case and "solutions" pages that connect business problems to APIs. This is where Pronovix finds "a quality collapse" on most portals. Treat it as a first-class layer, not filler. Their jury maxim: "Assume nothing, explain everything."
• Bottom layer - clean, minimal technical pages: reference, guides, console. Visual richness decreases at every step deeper.

Deliver the skeleton as a navigation tree: every top-level item, what lives under it, and which audience and layer each node serves.

3. Design the onboarding path to a TTFC target

Time to first call - landing on the portal to the first successful API call - is the governing metric.

• Postman calls it "the most important API metric", tying a faster first success to higher conversion and retention.
• Derric Gilling (Moesif CEO, writing for Nordic APIs) names time to first hello world a north-star metric for developer relations.

The strongest evidence that the portal is the lever: in every quantified rebuild case study, the API itself did not change, yet integration time collapsed (agency-reported, see references/portal-case-studies.md for all of them with sourcing labels).

• 20 days to 7.
• 2 months to 10 days.
• One rebuild landing at a 15-20 minute TTFC.

Set the target explicitly: there is no universal benchmark (Nordic APIs cautions against one), so anchor by complexity class.

• Ably's portal-scoring rubric awards top marks under 30 minutes.
• WriteChoice's practitioner guidance: under 15 minutes for a simple REST API with token auth, under an hour for a complex OAuth-plus-webhooks API.
• Twilio's public target, the most aggressive, is 5 minutes.

Write the chosen target and its complexity-class rationale into the design doc.

Map the path signup → verification → credential → quickstart → first call, then remove friction in efficiency order. Each rung below is sourced, but the ordering across rungs is synthesized from the friction literature rather than taken from a published ranking - treat it accordingly:

• value: auto-provisioned key with injected credentials > personalized onboarding > ready-to-run call collection > ungated exploration

• effort: personalized onboarding > auto-provisioned key with injected credentials > ready-to-run call collection > ungated exploration

• efficiency: ungated exploration > ready-to-run call collection > auto-provisioned key with injected credentials > personalized onboarding

• Default rung: ungated exploration. Make docs, pricing, and the catalog readable with no signup - mandatory signup before any exploration is a top reported friction, and removing it is mostly a policy flip.

• Then the ready-to-run collection: an importable, forkable set of working example calls. Postman, measuring on its own platform, reports a 1.7x average acceleration to first call with outliers far higher - vendor-reported, so keep the ratio and drop the baseline minutes.

• Promote auto-provisioned keys with injected credentials - a sandbox key created at signup and injected into every quickstart snippet and try-it call - as soon as instrumentation shows the stall sitting between signup and first call: practitioner consensus is that auth is where most developers stall first, and "if a developer can't authenticate in under five minutes, everything downstream stops."

• Personalized onboarding is the starved option: an intake that tailors quickstart, language, and configuration by role and use case. Highest value and highest effort, so it loses every efficiency round. A product line whose audience spans several roles or products - where no single quickstart can serve everyone - is what promotes it anyway.

This ordering is a default, not a law. Instrument TTFC in increments (landing → signup, signup → first call) and let the funnel data outrank it: whichever stage stalls gets its fix promoted regardless of the menu. Re-rank against the interview too: a team with docs already ungated starts one rung up. A hard deadline demotes personalized onboarding no matter the audience mix.

4. Place every surface

The portal is the container. Sibling skills own each surface's content. Decide placement, entry points, and navigation here:

Component	This skill owns	Sibling skill owns
API keys	The key dashboard's place in the IA and its self-service lifecycle UX	samber/developer-platform-skills@api-auth-key-management - key formats, scoping, and rotation mechanics
Request logs and delivery status	That integration logs have a first-class home	samber/developer-platform-skills@integration-error-observability - what those logs contain and how failures surface
Sandbox	The sandbox entry point and the test/live mode toggle's placement	samber/developer-platform-skills@api-test-mode-design - test keys, fixtures, and simulated events
API reference	The reference as a docs entry point generated from the spec, with a try-it console on the endpoint page	samber/developer-platform-skills@api-reference-quality - the reference content's completeness and quality
Status page	The status link's placement as a trust signal	samber/developer-platform-skills@api-status-communication - the status page and incident-communication practice itself
Error catalog	Hosts the published error-code catalog that documentation_url fields point at	samber/developer-platform-skills@api-error-design - the codes and messages themselves
Docs site IA	The portal container that documentation plugs into	samber/developer-relations-skills@developer-docs-structure-audit - the documentation site's internal structure
Quickstart page	The path leading to it, and measures TTFC around it	samber/developer-relations-skills@developer-quickstart-guide - the single zero-to-first-success page

Complete the placement pass with items that need a deliberate home even though no sibling owns them:

• Usage metering and quota visibility.
• Billing/plan management.
• Changelog and release notes.
• Support escalation path.

See references/component-checklist.md for the full component checklist and per-component design notes.

5. Design search and the AI assistant

An AI answer assistant next to search has moved from nice-to-have to expected component. Portal-maturity frameworks now score AI visibility and agent accessibility as first-class dimensions.

• Ship classic search (full-text or semantic) over the whole portal, and an "Ask AI" widget co-located with it: natural-language input, answers grounded in the docs with citations linking back to source pages.
• Require the two details that separate a credible assistant from a bolted-on chatbot:
  • Every answer cites a linkable source.
  • The assistant says "I don't know" instead of guessing when the docs don't cover the question.
• Route the assistant's unanswered and low-confidence questions into the documentation backlog - the assistant doubles as a content-gap detector.
• Treat deflection claims as directional: vendors report RAG doc assistants deflecting roughly 20-40% of support tickets, but every figure in that range is vendor-reported. Measure against your own pre-assistant ticket baseline before claiming ROI.

6. Design RBAC and tenancy

• Use the prevailing two-level hierarchy: Organization → Project/Workspace, with credentials, usage, and environments scoped to the project level.
• Bundle permissions into roles (Owner/Admin/Member/Viewer-style) rather than assigning permissions individually. Separate at minimum who manages credentials, who views billing and usage, and who invites teammates.
• Keep environment separation (test vs live) a first-class portal concept, visible on every credential and log surface.
• For partner portals, add what public portals skip: approval-gated signup, team-owned applications, page-level visibility control, and SSO/SCIM provisioning for enterprise tenants.

7. Decide build vs buy

• value: custom build > assembled stack > managed platform

• effort: custom build > assembled stack > managed platform

• efficiency: managed platform > assembled stack > custom build

• Default rung: buy a managed platform - a portal bundled with your API gateway or a hosted docs/portal product. The

...