docs: Improved Welcome and Quick Start pages for clarity, structure, and onboarding UX

[hashirshoaeb]

Status

READY

---

Description:

Summary

Rewrites the Welcome (/) and Quick Start (/getting-started) pages, taking
inspiration from Vercel, Next.js, and Flutter docs, and applying Google's
Technical Writing One principles.

---

Welcome Page (/)

Added

• Product description — "What is Shorebird?" section so first-time visitors
  immediately understand what the product does
• Prerequisites section with Flutter and Git requirements before the CTA
• "Explore the Docs" section with navigation cards to Getting Started,
  Code Push, and CI Integration

Fixed

• Removed Welcome page from sidebar — root / pages are conventionally
  hidden from navigation
• Weak, vague intro replaced with a clear one-liner that sets reader
  expectations (ref)
• Passive voice: "can be contacted in a variety of ways" →
  "Reach us through any of these channels"
  (ref)
• Removed duplicate: title and first line both said "Welcome"
• Typo: "advance usage" → "advanced usage"

---

Quick Start Page (/getting-started)

Added

• Scope statement at the top — defines what the guide covers and who it's for
  (ref)
• Prerequisites section (Flutter 3.24.0+, git)
• ## Installation heading to anchor the steps section in navigation
• "Install with AI" tab — a copy-pasteable prompt for LLM-assisted installation
• TODO placeholder for a 2-minute installation walkthrough video

Fixed

• Removed duplicate "Welcome to Shorebird! 👋" (also present on the Welcome page)
• Removed filler sentences:
  • "In this guide, we'll walk you through setting up Shorebird..."
  • "Your now ready to add Shorebird to your app." (also a typo)
  • "Now that your account is set up and your app is initialized, you're all set to begin."
  • "The first thing you'll need to do is sign up..."
• Passive voice and hedging in Install section intro removed
• Removed the full shorebird CLI help output — unnecessary; shorebird --help
  and shorebird doctor serve this purpose better
• Added terminal restart instruction before verification step (shorebird doctor)
  — the PATH is not reloaded without it
• Wrapped all steps in Starlight's
  <Steps> component for
  clear visual sequencing
• Used <Tabs> for conditional steps:
  • Install method: Install with AI | Install Script | Manual Install
  • Integration: New App | Existing App
    (ref)
• Updated page description frontmatter from "The easy way to get started with
  Shorebird" to "Install Shorebird and push your first patch."

---

Further Improvements (out of scope for this PR)

• Add a FAQ section
• Explicitly document supported platforms and OS versions
• Embed a 2-minute video tutorial on the Quick Start page
• Move the CI section lower in the sidebar (currently high priority placement)
• Replace Flutter Concepts section with redirect links to the Flutter blog —
  the docs should focus on Shorebird-specific content
• Byte-sized YouTube tutorial series (inspired by Flutter's Widget of the Week),
  embedded per feature in the relevant doc page
• Add pages for changelogs, what’s new and migrations
• Demos and Tutorials in the docs

---

[hashirshoaeb]

There is build error. I'll push the fix.

[hashirshoaeb]

Update: code is formatted and build successfully.

[hashirshoaeb]

Hey @tomarra, PR is ready to be reviewed. :)

[nickshorebird]

LGTM - Nits otherwise.

[AbhishekDoshi26]

Rest looks good, just some small changes :)

[AbhishekDoshi26]

This needs to be included. You can add this after the successful installation note.

[hashirshoaeb]

I've considered including the output, but I'm leaning against it for a few reasons:

the help text can change between CLI versions (creating maintenance overhead), and users can always run shorebird --help to see the latest commands. This is also consistent with how most modern CLI tool docs handle it (e.g., Vercel, Flutter).

That said, I'm happy to add a short line like: "Run shorebird --help to see all available commands." this acknowledges what's available without duplicating content. Would that work for you? But If you think it is still worth it, I'll revert and add back.

[AbhishekDoshi26]

Yes, we can include the shorebird --help command

[hashirshoaeb]

pushed.