Skip to content

☔ Focused initial get started flow around web hot reload #11911

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
parlough opened this issue Apr 17, 2025 · 1 comment
Open

☔ Focused initial get started flow around web hot reload #11911

parlough opened this issue Apr 17, 2025 · 1 comment
Assignees
@parlough @sfshaza2
Labels
a.get-started Relates to the Getting Started section of docs.flutter.dev e4-months Effort: 1+ months infra.structure Relates to the tools that create docs.flutter.dev p1-high Major but not urgent concern: Resolve in months. Update each month. target.web Target apps on the web platform

Comments

@parlough
Copy link
Member

parlough commented Apr 17, 2025 •
edited
Loading

Objective

Help developers set up Flutter and quickly experience some of its excellent developer experience features.

Problems

  • Following the current "Get started" flow requires developers to make multiple choices that are unnecessary at that stage or they might not understand.
  • Each platform's setup instructions are quite verbose with lots of validation built in, resulting in a long setup experience.
  • Not all of the current "Get started" flows can end in trying out important features like hot reload.
  • The different docs to add a target platform require making confusing choices about what platforms you already have set up.

Goals

  • Reduce the amount of steps developers follow to run their first Flutter app in the "Get started" flow.
  • Don't force developers to choose a platform to develop for right away.
  • Help developers quickly try out some of Flutter's developer experience features, at least including hot reload.
  • Direct developers who successfully set up Flutter to next steps, including learning resources (FWE) and how to develop for other platforms besides web.
  • Don't require developers to make choices or remember their setup in the "developing for a new platform" docs.

Non-goals

  • Reduce the amount of dependencies needed to develop for any of Flutter's supported platforms.
  • Create new tooling to help developers install necessary dependencies.
  • Write significant new installation content. Most should be able to be reorganized and reused from current installation and platform support docs.
  • Add significant new beginner learning content. That work will be completed separately as part of the FWE/GSE projects.
  • Expanding docs to cover setup for other platforms.

Assumptions

  • Hot reload on web will be stable.
  • Most new developers don't mind the happy path's choice of relying on VS Code.
  • Developers already have Chrome installed or will have no problem installing it.

Documentation plan

Get started overhaul

  • (Must have) /get-started
    Title: Get started developing with Flutter
    Content: Happy path of installing Flutter with VS Code plugin, running app on web, (maybe have) trying hot reload, (maybe have) trying DevTools/flutter panel.
  • (Could have) /get-started/codelab
    Title: Write your first Flutter app
    Content: Existing, but update to highlight ability to easily develop on web.
  • (Could have) /get-started/learn
    Title: Learn Flutter development
    Content: Index of options and resources to learn Flutter development after setup.

Install guides and references

  • (Could have) /install
    Title: Install Flutter
    Content: Index of various installation options.
  • (Must have) /install/manual
    Title: Install Flutter manually
    Content: Installing Flutter manually with archive zip or git in terminal.
  • (Should have) /install/vs-code
    Title: Install Flutter using VS Code
    Content: Shared instructions with getting started flow.
  • (Should have) /install/troubleshooting
    Title: Troubleshoot Flutter installation
    Content: An index of known issues and their solutions during Flutter installation.
  • (Should have) /install/upgrade
    Title: Upgrade Flutter
    Content: Mostly existing content relocated.
  • (Could have) /install/uninstall
    Title: Uninstall Flutter
    Content: Mostly existing content relocated.
  • (Could have) /install/system-requirements
    Title: Development system requirements
    Content: The latest known system requirements for development environments.
  • (Could have) /install/add-to-path
    Title: Add Flutter to your system path
    Content: Instructions on how to add Flutter to your PATH.

Develop for new platform

  • (Must have) /platform-integration/ios/setup
    Title: Set up iOS development
  • (Must have) /platform-integration/android/setup
    Title: Set up Android development
  • (Must have) /platform-integration/web/setup
    Title: Set up web development
  • (Must have) /platform-integration/macos/setup
    Title: Set up macOS development
  • (Must have) /platform-integration/windows/setup
    Title: Set up Windows development
  • (Must have) /platform-integration/linux/setup
    Title: Set up Linux development
  • (Could have) /platform-integration/setup
    Title: Set up development for a new platform
    Content: Index for setting up your system to develop for a new platform.
  • (Could have) /platform-integration/add-new-platform
    Title: Best practices for bringing your app to a new platform

Testing and metrics

Setup time reduction:

  • (?) User testing of time to running app before and after new docs.

Setup completion:

  • Analytics of amount of developers continuing to the "Create your first Flutter app" codelab page.
  • CLI analytics for hot reload usage on web.

Setup success:

  • Analytics of developers visiting install troubleshooting page.
  • Monitoring of Flutter Forum help category, FlutterDev #install-and-setup channel, and StackOverflow.

Desire to develop for other platform:

  • Analytics of which platform's docs navigated to from "Next step" after set up.

Release criteria

  • All "Must have" docs above written or with alternative.
  • Hot reload support for web released.
  • All existing install and get started links have reasonable redirect destinations.

Questions

  • Should we include the first run and hot reload in the primary "Get started" flow or should we rely on the Write your first Flutter app codelab which already does and update that to mention web?
  • Should the "Get started" page start with a call out to instead using DartPad and/or Firebase Studio to quickly try out Flutter in their browser?
@parlough parlough added a.get-started Relates to the Getting Started section of docs.flutter.dev e4-months Effort: 1+ months infra.structure Relates to the tools that create docs.flutter.dev p1-high Major but not urgent concern: Resolve in months. Update each month. target.web Target apps on the web platform labels Apr 17, 2025
@parlough parlough self-assigned this Apr 17, 2025
@parlough parlough mentioned this issue Apr 17, 2025
Merged
sfshaza2 pushed a commit that referenced this issue Apr 17, 2025
@parlough
Remove mostly duplicated web-specific get started codelab (#11912)
51f8111 
This version of the getting started codelab hasn't been updated in a lot
time and with Filip's ["Your first Flutter app"
codelab](https://docs.flutter.dev/get-started/codelab), it's mostly
duplicated content. We prefer developers following that one and
according to analytics, they mostly do.

This PR then redirects from the removed page to the preferred codelab's
introduction.

Contributes to #11911 by
starting to clean up the getting started section and reducing
duplication of the content that it will add.
@parlough parlough changed the title ☔ Create simplified initial get started flow based on developing for web ☔ Get started with Flutter like a web-building spider Apr 17, 2025
@parlough parlough changed the title ☔ Get started with Flutter like a web-building spider ☔ Get started with Flutter like a web-weaving spider Apr 17, 2025
@parlough parlough changed the title ☔ Get started with Flutter like a web-weaving spider ☔ Focused initial get started flow around web hot reload Apr 17, 2025
@parlough
Copy link
Member Author

parlough commented Apr 22, 2025 •
edited
Loading

Tasks to implement plan as proposed:

Phase 0

Phase 1

Phase 2

Phase 3

Phase 4

  • Write new, single-page /get-started with setup happy path

Phase 5

Depends on web support for hot reload being in stable, not behind a flag.

  • Update /get-started/codelab for web supporting hot reload

Related/extra

  • Write /platform-integration/add-new-platform best-practices guide

This was referenced Apr 28, 2025
Draft
Merged
sfshaza2 pushed a commit that referenced this issue Apr 28, 2025
@parlough
Introduce a new /install root directory (#11951)
8e85e92 
- Adds a new index page and directory at `docs.flutter.dev/install`
- Moves the `/get-started/uninstall` page to `/install/uninstall`
- Moves the `/release/upgrade` page to `/install/upgrade`

Contributes to #11911

**Staged:**
https://flutter-docs-prod--pr11951-feat-install-directory-8n0cctp3.web.app/install
parlough added a commit that referenced this issue Apr 28, 2025
@parlough
Delete various unused includes (#11952)
dfa20a4 
Contributes to #11911
@parlough parlough mentioned this issue Apr 28, 2025
Merged
@parlough parlough mentioned this issue Apr 28, 2025
Merged
sfshaza2 pushed a commit that referenced this issue Apr 28, 2025
@parlough
Move install help page to new /install directory (#11954)
80d44f6 
- Moves `/get-started/install/help` to `/install/troubleshoot`
- Cleans up the page formatting and link references
- Updates the help icon include for improved accessibility

Contributes to #11911

**Staged:**
https://flutter-docs-prod--pr11954-misc-install-troubleshootin-5xquyl0u.web.app/install/troubleshoot
parlough added a commit that referenced this issue Apr 29, 2025
@parlough
Move editor setup instructions to their respective pages (#11955)
0429795 
Moves the setup instructions with some minor cleanup from
https://docs.flutter.dev/get-started/editor to each editor's respective
page. The old page will be removed as part of follow up work as there
are still some dependencies on it.

Contributes to #11333 and
#11911
@parlough parlough mentioned this issue Apr 29, 2025
Merged
sfshaza2 pushed a commit that referenced this issue Apr 29, 2025
@parlough
Move and update the editors index/setup page (#11956)
f2a6ece 
- Move `/get-started/editors` to `/tools/editors`
- Remove the setup instructions
- These were moved to the individual editor pages in
#11955.
- Update the page with a new index of editor support, with a section for
local editors, online editors, and other/unsupported editors.

Resolves #11333
Contributes to #11911

**Staged:**
https://flutter-docs-prod--pr11956-feat-11333-yuqts3as.web.app/tools/editors
This was referenced May 8, 2025
Merged
Merged
sfshaza2 pushed a commit that referenced this issue May 8, 2025
@parlough
Standardize web setup instructions (#11984)
88e0637 
Following the format of #11968

Contributes to #11911

**Staged:**
https://flutter-docs-prod--pr11984-feat-web-setup-instructions-5i2qiffj.web.app/platform-integration/web/setup
sfshaza2 pushed a commit that referenced this issue May 8, 2025
@parlough
Add standalone 'Install using VS Code' page (#11992)
f3520c7 
For now, it's not linked to anywhere or in the sidenav, but that will
change once some other necessary content lands.

Part of #11911

Some of this content is duplicated from elsewhere. Once every part of
this issue lands, some pieces might be extracted to partials where
helpful.

**Staged:**
https://flutter-docs-prod--pr11992-feat-install-with-vs-code-6qmcg59p.web.app/install/with-vs-code
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@parlough parlough

@sfshaza2 sfshaza2

Labels
a.get-started Relates to the Getting Started section of docs.flutter.dev e4-months Effort: 1+ months infra.structure Relates to the tools that create docs.flutter.dev p1-high Major but not urgent concern: Resolve in months. Update each month. target.web Target apps on the web platform
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@parlough @sfshaza2