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

parlough · 2025-04-17T00:38:42Z

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?

The text was updated successfully, but these errors were encountered:

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 · 2025-04-22T19:40:05Z

- 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

Contributes to #11911

- 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

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

- 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

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

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

gitslav · 2025-05-09T09:25:54Z

Hey @parlough thanks for working on this. Yesterday I had to go through the setup of a new Mac and the setup documentation is much worse than what it was some years ago. Actually the user experience of initial setup and awesome documentation was what made me pick Flutter.

parlough · 2025-05-09T21:31:42Z

Hey @parlough thanks for working on this.

Thank you for noticing this and providing this feedback! I really appreciate it.

Yesterday I had to go through the setup of a new Mac and the setup documentation is much worse than what it was some years ago.

I'm sorry about that! Some of the changes were necessary and had good intentions, but were never able to be brought to full fruition.

If you have any specific feedback or pain points from this time around, please do let me know. I'll try to account for that as we work on this overhaul and simplification.

Actually the user experience of initial setup and awesome documentation was what made me pick Flutter.

I'm glad, that's real nice to hear :)

I hope our setup docs and experience can get there again! We're trying to land these improvements quickly and there's other areas and tooling being explored to streamline the flow as well, but hopefully these doc improvements are a step in the right direction. Thank you!

Some new content, some extracted from the existing get started flow with simplifications. Part of #11911 **Staged:** https://flutter-docs-prod--pr11999-feat-add-to-path-1qnmz0sc.web.app/install/add-to-path

Following the format of #11968 Contributes to #11911 **Staged:** https://flutter-docs-prod--pr12005-feat-setup-windows-ma59a9vu.web.app/platform-integration/windows/setup _Replaces: https://docs.flutter.dev/platform-integration/windows/install-windows_

Following the format of #11968 Contributes to #11911 **Staged:** https://flutter-docs-prod--pr12003-feat-macos-setup-bq24qf6n.web.app/platform-integration/macos/setup _Replaces: https://docs.flutter.dev/platform-integration/macos/install-macos_

Following the format of #11968 Contributes to #11911 **Staged:** https://flutter-docs-prod--pr12004-feat-linux-setup-3ujw5efj.web.app/platform-integration/linux/setup _Replaces: https://docs.flutter.dev/platform-integration/linux/install-linux_

Updates the formatting of the new `/platform-integration/ios/setup` page to be consistent with the current state of the others. Then fully replace the old page, removing them and adding redirects. Contributes to #11911 **Staged:** https://flutter-docs-prod--pr12007-feat-standardize-ios-setup-jxytw7k0.web.app/platform-integration/ios/setup --------- Co-authored-by: Loïc Sharma <[email protected]> Co-authored-by: Jenn Magder <[email protected]>

Adds a page that covers manual installation of Flutter, partially reusing existent content but with simplifications and reformatting. Contributes to #11911

Also introduces a new set up flow that utilizes the new separated docs on the install index page: https://flutter-docs-prod--pr12013-feat-install-flow-9x48m1eo.web.app/install#get-started Contributes to #11911

Standardize the uninstall docs with the new format used by the rest of the [new installation docs](https://docs.flutter.dev/install) and fix some related issues. Contributes to #11911 Fixes #12009 **Staged:** https://flutter-docs-prod--pr12029-feat-uninstall-standardize-ihkcdxc9.web.app/install/uninstall

The work in #11911 will eventually supersede these docs, but to ease that transition and make it easier to review complete some preliminary cleanup and small fixes. - Removes old includes that weren't used anymore recently landed changes - Inlines use of most remaining includes to simplify maintenance and eventual removal - Remove various usages of liquidjs templating where unnecessary or overcomplicated - Removes some verbose terminal output where hard to keep up to date - Removes some outdated/unlikely troubleshooting asides in favor of linking to official, external docs. - Removes a few mentions of specific software versions. Contributes to #11911 Contributes to #11907 Fixes #11997 Closes #10963 Closes #10884 Resolves #10885

The work in #11911 will eventually supersede these docs, but to ease that transition and make it easier to review complete some preliminary cleanup and small fixes. Contributes to #11911 Resolves #11907

parlough self-assigned this Apr 17, 2025

parlough mentioned this issue Apr 17, 2025

Remove mostly duplicated web-specific get started codelab #11912

Merged

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 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 changed the title ~~☔ Get started with Flutter like a web-weaving spider~~ ☔ Focused initial get started flow around web hot reload Apr 17, 2025

This was referenced Apr 28, 2025

[WIP] Experiment with simplified get started flow #11944

Closed

Introduce a new /install root directory #11951

Merged

parlough added a commit that referenced this issue Apr 28, 2025

Delete various unused includes (#11952)

dfa20a4

Contributes to #11911

parlough mentioned this issue Apr 28, 2025

Move install help page to new /install directory #11954

Merged

parlough assigned sfshaza2 Apr 28, 2025

parlough mentioned this issue Apr 28, 2025

Move editor setup instructions to their respective pages #11955

Merged

parlough mentioned this issue Apr 29, 2025

Move and update the editors index/setup page #11956

Merged

This was referenced May 8, 2025

Standardize web setup instructions #11984

Merged

Add standalone 'Install using VS Code' page #11992

Merged

sfshaza2 pushed a commit that referenced this issue May 8, 2025

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

parlough mentioned this issue May 9, 2025

Standalone add to path instructions #11999

Merged

This was referenced May 12, 2025

Introduce single 'Set up macOS development' page #12003

Merged

Introduce single 'Set up Linux development' page #12004

Merged

Introduce single 'Set up Windows development' page #12005

Merged

parlough mentioned this issue May 12, 2025

Finalize switch to new iOS setup page #12007

Merged

parlough mentioned this issue May 13, 2025

Add standalone doc covering manual installation #12011

Merged

parlough added a commit that referenced this issue May 13, 2025

Add standalone doc covering manual installation (#12011)

5f059b2

Adds a page that covers manual installation of Flutter, partially reusing existent content but with simplifications and reformatting. Contributes to #11911

parlough mentioned this issue May 13, 2025

Add new install docs to sidenav #12013

Merged

This was referenced May 19, 2025

Simplify setup of old setup docs #12026

Merged

Standardize uninstall docs with rest of new install docs #12029

Merged

parlough mentioned this issue May 19, 2025

Remove specific versions from old setup flow #12036

Merged

parlough mentioned this issue May 21, 2025

[Not to land] Add a quick version of getting started #12052

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

parlough commented Apr 17, 2025 •

edited

Loading

parlough commented Apr 22, 2025 •

edited

Loading

Uh oh!

gitslav commented May 9, 2025

Uh oh!

parlough commented May 9, 2025

Uh oh!

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

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

Comments

parlough commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Problems

Goals

Non-goals

Assumptions

Documentation plan

Get started overhaul

Install guides and references

Develop for new platform

Testing and metrics

Release criteria

Questions

parlough commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Phase 0

Phase 1

Phase 2

Phase 3

Phase 4

Phase 5

Related/extra

Uh oh!

gitslav commented May 9, 2025

Uh oh!

parlough commented May 9, 2025

Uh oh!

parlough commented Apr 17, 2025 •

edited

Loading

parlough commented Apr 22, 2025 •

edited

Loading