developer_portal_design v1.0.0

name: "developer_portal_design" description: "Design an external developer portal: information structure, the signup to first API call path, where keys, docs, status, and support live, search that finds error text, access roles, and a build or buy call with reasons recorded. Triggers when someone asks to design, audit, or fix a developer portal, docs site, or API dashboard, or to shorten time to first call."

Developer Portal Design

Purpose

Design a portal where a stranger can sign up, get a sandbox key, and make a first successful API call without help, then find keys, docs, status, and support again later without hunting. The portal is a product surface, not a docs folder with a login page bolted on.

Workflow

1. Map the portal before building any page. List every destination a developer needs and give each one home: home, quickstart, task guides, API reference, changelog, status, support, pricing and limits in public; keys, usage, webhooks, team, and app settings signed in. Use the worked map in references/portal-map-example.md as the starting shape and cut or add pages only with a reason written down.
2. Make docs and reference public by default. Keep the quickstart, guides, reference, changelog, and status readable without login. Gated docs hide error text from search engines and from the portal's own index, and they add a step before the first call. Gate only keys, usage data, and account settings.
3. Design the signup to first call path as one timed path. Self-serve signup, no sales call and no manual approval for sandbox access. Create the sandbox key automatically at signup or in one click. The quickstart completes one real task end to end, not just an auth check, with a copy-paste example whose key slot is obvious. Pre-fill that example with the reader's test key when they are signed in.
4. Run the timed test, do not guess. Recruit or simulate a developer who has not seen the API. Start a timer at the portal home, stop it at the first successful call that completes the quickstart task. Record the total, every pause, and every place they searched or backtracked. Set a target before the test and write it down. Vendor guidance commonly cites under 5 minutes as a strong target and 5 to 15 minutes as a workable range; pick the target that fits the API's real setup cost, then treat misses as portal bugs, not user errors. Repeat the test after each fix with a fresh tester.
5. Place keys where developers expect them. One keys page that supports create, name, scope or restrict, reveal, rotate, and revoke. Separate test and live keys clearly with labels and separate lists, never colour alone. Show a secret once at creation and say so before the reader leaves the page. Document what a leaked key does, how rotation works without downtime, and how to use restricted or scoped keys for third parties, following the pattern Stripe documents for publishable, secret, and restricted keys.
6. Build search that finds error text. Index guides, reference, changelog, and support answers in one index on one domain. Test it with five real strings: an exact error code, an exact error message copied from a response, an endpoint path, a field name, and a plain task phrase like "refund a payment". Each query must return the page that fixes the problem in the first three results. If error text fails, the fix is indexing response examples and error catalogues, not a better search box.
7. Separate status, changelog, and support, and link all three everywhere. Status shows current state, component breakdown, incident history, and a subscribe option, and stays up when the main product is down, so host it separately. The changelog is dated, newest first, flags breaking changes in the entry title, and links to the migration guide. Support lists the community, the ticket route, and the expected first response time without requiring login to read them. Put status and support links in the portal header and footer, not only on a help page.
8. Set access roles by job, with least privilege. At minimum: owner (billing, delete app, manage owners), admin (team, keys, settings), developer (keys for own apps, webhooks, usage), billing (invoices and plans, no keys), and viewer (read docs, usage, and status, no secrets). A viewer must never be able to reveal a secret key, and removing a person must revoke their access without rotating shared keys, which means keys belong to the app or service account, not to a person.
9. Score the portal with the audit sheet. Fill in bin/portal_audit.py input honestly from the live portal, not from plans. Run it, fix the highest-weight missing items first, and re-run it. Do not call a portal ready below the ready grade in the tool output.
10. Record the build or buy call. Compare building on a static site plus a small dashboard against a hosted portal product on five points: control of the signup to first call path, search quality on error text, status hosting separation, key management work you still own either way, and total cost at expected developer count. Write the decision and the reasons in a short decision record with a revisit date. Hosted products speed up docs and reference; they rarely own your key, team, and billing logic, so budget for that integration either way.

Output Contract

• A portal map listing every public and signed-in page, what lives on each, and what was cut or added compared with the example map, with reasons.
• A timed signup to first call test report: target set in advance, measured time, tester background, every pause or backtrack, and the fixes assigned from it.
• An audit result from bin/portal_audit.py: score, grade, and the missing items in weight order, run against the live portal.
• A search test table with the five test strings, the top result for each, and pass or fail against the first-three-results bar.
• A roles table showing what owner, admin, developer, billing, and viewer can each see and do, with secret reveal restricted explicitly.
• A build or buy decision record: options compared on the five points in step 10, the choice, the reasons, and a revisit date.

Operating Rules

1. Time to first call means first successful call. The clock runs from accessing the portal or starting signup to a successful response that completes a real task. A 401, a docs page view, or an SDK install does not stop the clock.
2. Never gate the reference behind signup. If a prospect cannot read request and response shapes before signing up, they cannot evaluate the API, and error text stays unfindable.
3. One search index, one domain. Splitting guides, reference, and help across subdomains with separate indexes is the most common cause of failed error-text search.
4. Keys belong to apps, not people. Person-owned shared keys force a rotation and an outage risk every time someone leaves.
5. Status lives apart from the product. A status page hosted on the same stack that is down is a status page that is also down.
6. Do not invent adoption numbers or benchmarks. Targets in this skill are goals to set and test against, not industry facts. Label any external figure with its source or cut it.
7. Fix the path, not the tester. Every pause in the timed test is a portal defect with an owner and a fix, even when the tester also made a mistake a clearer page would have prevented.