docs(onboarding): streamline first-run experience for non-engineers and general adoption
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Problem
Buzz's onboarding experience currently assumes a high degree of technical fluency. For a platform that wants broad adoption — across product managers, designers, editorial teams, operations folks, and other non-engineers — the current setup process is a significant barrier to entry.
The gap isn't just "missing docs." It's that the entire onboarding flow (identity creation, community joining, agent configuration, provider setup) requires decisions and context that non-technical users don't have. When someone downloads Buzz for the first time, they should be able to go from zero to a working conversation with an agent in under 5 minutes without reading source code or understanding Nostr key management.
## Specific Gaps
1. **No guided first-run flow for "I just want to use this."** The current onboarding asks users to make decisions (relay URLs, key management, provider configuration) before they understand what those things are or why they matter. Non-engineers need a happy path that defers complexity.
2. **Agent setup requires too much configuration knowledge.** Setting up an agent to actually respond requires understanding providers, API keys, model selection, and MCP tools. A non-engineer who just wants to talk to an AI assistant shouldn't need to know what an MCP tool is.
3. **Documentation is developer-oriented.** README, CONTRIBUTING.md, and ARCHITECTURE.md are excellent for contributors but don't serve the "I downloaded this app, now what?" user. There's no user-facing guide that walks through common workflows without assuming terminal comfort.
4. **Error states during onboarding are cryptic.** When something goes wrong during setup (provider auth fails, relay connection drops, agent won't start), the feedback assumes the user can debug it. Non-engineers need actionable guidance, not stack traces.
5. **No "team admin sets it up, members just join" path.** In an org adoption scenario, one person (the admin/engineer) should be able to configure the community, agents, and providers — and then invite teammates who get a streamlined join experience with everything pre-configured.
## Proposed Improvements
- **Opinionated defaults for first-run.** Pick sensible defaults for relay, identity, and agent config so the user can skip decisions they don't care about yet. Let them customize later.
- **"Quick Start for Users" guide.** A standalone doc (not CONTRIBUTING.md) that walks a non-technical person from download → first agent conversation in under 5 minutes. Screenshots, no terminal commands.
- **Pre-configured agent templates.** "Start with a general assistant" that works out of the box with minimal config (just an API key). Advanced agent configuration is opt-in.
- **Invite-based team onboarding.** When joining via invite link, skip the decisions the admin already made. The new member gets a working environment immediately.
- **Human-readable error messages during setup.** Replace technical errors with guidance: "Your API key doesn't seem to work — here's how to get one from OpenAI" instead of a raw 401.
## Why This Matters for Adoption
Every person who downloads Buzz, gets confused during onboarding, and closes the app is a lost user. The technical depth of the platform is a strength for power users, but it needs to be layered — simple by default, powerful when you dig in. Right now the complexity is front-loaded, which filters for engineers and filters out everyone else.
## Related
- #3088 — Self-hosting onboarding is frustrating (same theme, narrower scope)
- #5064 — Onboarding cannot configure OpenAI-compatible base URLs (specific config gap)
- #2414 — FTUX onboarding scroll/button bug (UI issue within the existing flow)
Contributor guide
Research direction
Start by reviewing README, CONTRIBUTING.md, and ARCHITECTURE.md, then examine the existing onboarding flow and the related issues #3088, #5064, and #2414. Done means defining and implementing a user-facing path from download to a first agent conversation in under five minutes, with simpler setup, team invites, and actionable onboarding errors.
Written by the indexing model from the issue text.
Assessment
- Domain
- design, developer-experience, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100