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. :)