block / block/buzz

docs(onboarding): streamline first-run experience for non-engineers and general adoption

Open
#5,527 0 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.