Skip to content

docs: make README beginner-first with quickstart and troubleshooting#24

Merged
Ansub merged 1 commit intomainfrom
docs/readme-beginner-friendly
Feb 25, 2026
Merged

docs: make README beginner-first with quickstart and troubleshooting#24
Ansub merged 1 commit intomainfrom
docs/readme-beginner-friendly

Conversation

@Ansub
Copy link
Copy Markdown
Owner

@Ansub Ansub commented Feb 25, 2026

Why

The README had strong content, but new users had to scan multiple sections before getting a reliable first success. This PR optimizes for a beginner-first setup flow.

What Changed

  • Added a top-level Start Here (2 to 5 minutes) section with copy/paste commands.
  • Added explicit expected results after install/verify/customization steps.
  • Reorganized setup into Prerequisites, Install, and Verify It Worked.
  • Reworked troubleshooting by symptom (command not found, changes not applying, doctor issues).
  • Consolidated command docs under Common Tasks with clearer labels.
  • Moved reload internals to Advanced Notes to reduce initial cognitive load.
  • Surfaced backup/restore safety notes near install.

Scope

  • Docs-only change (README.md)
  • No CLI or runtime behavior changes

Reviewer Checklist

  • Follow the Start Here block in order and confirm it reads clearly for first-time users.
  • Confirm command examples are valid (boo theme, boo opacity, boo prompt, boo doctor, boo reload).
  • Confirm troubleshooting covers the top failure paths with direct next steps.
  • Confirm advanced details are discoverable but not blocking the first run.

Testing

  • Manual docs QA only (no code changes)

Follow-Up Ideas (separate PR)

  • Add screenshots/GIFs for boo status and a theme switch.
  • Add a compact command glossary table for absolute beginners.
  • Add a one-screen "ultra-quickstart" at the top for skimmers.

@Ansub Ansub merged commit e2845d5 into main Feb 25, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant