Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

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

Open
hashirshoaeb wants to merge 12 commits into
shorebirdtech:main from
hashirshoaeb:doc-review
Open

docs: Improved Welcome and Quick Start pages for clarity, structure, and onboarding UX #546
hashirshoaeb wants to merge 12 commits into
shorebirdtech:main from
hashirshoaeb:doc-review

Conversation

@hashirshoaeb

@hashirshoaeb hashirshoaeb commented May 27, 2026 •
edited
Loading

Copy link
Copy Markdown

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
 

...g UX
 - Remove Welcome from sidebar (root pages conventionally hidden)
 - Add product description, prerequisites, and nav cards to Welcome page
 - Add scope statement, prerequisites, and Installation heading to Quick Start
 - Wrap steps in <Steps> component; use <Tabs> for install method and app type
 - Add "Install with AI" tab with copy-pasteable LLM prompt
 - Remove shorebird CLI help output dump; use `shorebird doctor` instead
 - Add terminal restart instruction before PATH verification step
 - Fix passive voice, typos, filler sentences, and duplicate welcome messages
@hashirshoaeb hashirshoaeb changed the title (削除) docs: improve Welcome and Quick Start pages for clarity, structure, and onboarding UX (削除ここまで) (追記) docs: Improved Welcome and Quick Start pages for clarity, structure, and onboarding UX (追記ここまで) May 27, 2026
@hashirshoaeb hashirshoaeb marked this pull request as ready for review May 27, 2026 02:35

Copy link
Copy Markdown
Author

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

Copy link
Copy Markdown
Author

Update: code is formatted and build successfully.

Copy link
Copy Markdown
Author

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

@nickshorebird nickshorebird left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM - Nits otherwise.

Comment thread src/content/docs/getting-started/index.mdx
Comment thread src/content/docs/index.mdx Outdated
Comment thread src/content/docs/getting-started/index.mdx Outdated

@AbhishekDoshi26 AbhishekDoshi26 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rest looks good, just some small changes :)

Comment thread src/content/docs/getting-started/index.mdx Outdated
Comment on lines -96 to -109
Available commands:
cache Manage the Shorebird cache.
doctor Show information about the installed tooling.
flutter Manage your Shorebird Flutter installation.
init Initialize Shorebird.
login Login as a new Shorebird user.
login:ci Login as a CI user.
logout Logout of the current Shorebird user
patch Creates a shorebird patch for the provided target platforms
patches Manage Shorebird patches
preview Preview a specific release on a device.
release Creates a shorebird release for the provided target platforms
releases Manage Shorebird releases
upgrade Upgrade your copy of Shorebird.

@AbhishekDoshi26 AbhishekDoshi26 Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@hashirshoaeb hashirshoaeb Jun 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 AbhishekDoshi26 Jun 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we can include the shorebird --help command

@hashirshoaeb hashirshoaeb Jun 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pushed.

Comment thread src/content/docs/getting-started/index.mdx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nickshorebird nickshorebird Awaiting requested review from nickshorebird

@AbhishekDoshi26 AbhishekDoshi26 Awaiting requested review from AbhishekDoshi26

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /