Getting Started experience

[miguelsolorio]

Overview

When opening VS Code for the first time, it can be intimating to figure out how to configure the editor to best meet your needs and workflow. This is even more so for students and those learning new languages. This issue aims to explore what a first run user onboard experience could look like. This will walk the user through the basic core features of using the editor (themes, command palette, extensions) while also teaching users how to access certain features.

Designs

[gulshan]

Please make "Git clone" a part of the onboarding experience.

[nrayburn-tech]

Two settings that may be worth showing for macOS (and maybe Linux) are adding an option to the os context menu and adding “code” to path.

macOS doesn’t use an installer, so these are currently added by running editor commands which can be hard to find if you don’t know what you’re looking for. (Context menu isn’t added yet, but without an installer the editor command is the way it will be added.)
#105448 (comment)

[miguelsolorio]

Thanks for the suggestions! @gulshan I think adding a step for cloning a repo makes sense, though this will require authentication if they haven't set it up. @nrayburn-tech I like the option for adding code to the path as well, not sure about the context menu one as that feels pretty specific and more of an advanced usage.

[miguelsolorio]

Based on the feedback I've received so far (speed up animations, add more themes, adding more options like cloning and adding code to the path), I've updated the flow to include these, see the updates below.

[orta]

I love it.

Depending on how much friction you want to offer on the onboarding, that command palette page could require the user to run an action in the command palette. e.g The "Next Step" button could turn to "Unlock via the palette" and be disabled until you run the only possible command in the palette of "Unlock"

[miguelsolorio]

@orta it's funny you mention that, @JacksonKearl also suggested the same thing. Maybe we really should do that 😁

[GustavoASC]

I am really, really excited about this! It will be a great user experience!!!! Congrats for the great work 👏 👏 👏

[alexweininger]

This is awesome! Really exciting to see this in the works. 😃

I believe larger, feature-rich, extensions would really benefit from providing users with their own first run onboard experience similar to the one in the designs.

It would be awesome if this feature could be offered through the extension API in some form. That way extensions could contribute their own first-run experience. Extensions could use this to show new users around the extension, similar to how the experience in the designs shows users around VS Code.

[iyashpal]

Really excited to have this functionality. Please make this available in upcoming release.

[ntotten]

Love it! This would be something we would love to use in the Salesforce extensions as well. Having an API to allow extensions to add to this would be really useful.

[miguelsolorio]

Thanks everyone for the feedback so far. Writing down additional feedback I received during the team's weekly ux sync:

• The themes + extension sections should have an entry point to access more (show color theme picker + extension view)
• Maybe the themes should be simplified to only have dark + light + link to others
• The command palette felt odd in the flow, maybe have that at the end or make it part of the "get started" todo
• Command palette screenshot needs better examples, we could show most popular commands
• Extension should have a better order and make languages the default tab
• We could also add section for "Environments" to show OS specific extensions
• Could also add this to the "get started" todo (i.e. WSL extension on Windows)
• The "good to go" actions felt repetitive with what's already in the "get started" todo
• We could get rid of the "good to go" section and go directly into the interface overview
• The onboard should be bundled into the "welcome" page so there isn't multiple tabs open
• There should be an entry point in the welcome page to revisit the onboard walkthrough
• If we can detect if a user has ST or VIM installed we can offer keymap suggestions

[sana-ajani]

I love this experience! I wonder if we can also include something to help students learn to code once they learn the editor. We saw from user studies with students that many of them wanted or expected to find in-product tutorials. Could we potentially include an option to "launch tutorials" under the "Learn" section of the Welcome page? It could open a quick pick where students choose the language of the tutorial they want to do and if they want to do it in the editor or go to our website/docs. If they choose the one in the editor, we could open up a split screen with a tutorial in webview that helps them install the extension if they haven't, create a folder or file, open the terminal, and write their first few lines of code and learn how to run it.

[hollyhet]

This is beautiful, Miguel and so needed. The one thought I had based on earlier sessions with students and educators is can we simplify some of the terminology and make it less jargony? Ex: Do they absolutely need to know that a repository is being cloned in order to take a tour of the UI, or can the button just say "Tour UI" and elsewhere we communicate that a repository is being cloned? I also noticed that the titles for each of the screens aren't consistent in terms of phrasing. Some of them are more descriptive and action-oriented (ex: "Choose a theme") and some require more interpretation on the reader's part (ex: "Command palette") What if customers don't know what a command palette is? What is the value of the command palette? What does it do for them? What do they need to do with it? There may be value in simplifying phrasing and focusing on the feature values for ALL new customers, not just students and educators.

[JacksonKearl]

What if customers don't know what a command palette is? What is the value of the command palette?

I think this is a good point, perhaps if the title was "Run Any Command" or similar?

[NeelAPatel]

Setting default terminal should be a thing as well, I find myself always making sure Bash becomes my default, increasing tree indentation width and reducing minimap width.

Inshort, Onboarding should deal with settings that a user sees the most frequently: Theme, Terminal, Git, and File tree (indentation/icons) at the very least.

[cmchap]

I agree with many of the above comments that the power of the Command Palette is under emphasized.

Maybe combine the Command Palette with the other steps to give a bit of interactivity to the flow. Show the pictograms for the themes, then ask users to invoke the Command Palette to change their theme, for instance. I'd bet there are other opportunities for learning-by-doing with the Command Palette in this workflow, too.

[obiwanjacobi]

1. Make the command palette bar (Ctrl+Shift+P) part of the welcome screen. Explain it there.
   Also make it a menu option (or a button somewhere).
   It is the most essential step that is not explicitly visible. You cannot discover it by browsing through the app.

2. Git. Explain how the UI relates to the Git commands (most are obvious). Link to other source control extensions?

3. Extensions. Perhaps prepare packages (a collection of extensions) that work well together for a specific goal. Programming in C# or Web with TypeScript etc.

4. Tasks & Debug. How do you build and run your project? How do all these .vs files (launch/settings/tasks) work? How are they linked to the vscode UI?

[2c]

[GV14982]

Something I would love to see added is a settings sync prompt!

*DOH it's already there... lol!

[kimbar]

The fact: the culprit for slow operation is always too many extensions or one rouge one.

However, it would be nice to have some obvious way to profile performance of extensions (something like unix top command)

[hwine]

You show, but don't explain, "workspace" and "folders". Why do they need that extra level of organization?

(I've been using vscode for about 6 months, and I still don't understand.)

[miguelsolorio]

Thanks everyone for the feedback so far! We've received some great ideas and have also done a couple of user studies with new users that highlighted some areas for improvement.

We've updated the flow to incorporate some of these ideas and have really focused on teaching the users how to use the tool as opposed to showing them. We've also tried to improve the wording on the titles so we don't rely on words the users does not know/understand. Lastly, at the end of the gif I show some improvements we're working on making to the new welcome screen.

[iyashpal]

This is actually mind blowing.

[yanjiang222]

I love it!

• We're making a new vs code toolkit and think of leveraging this to our toolkit onboarding experiences. It would be great if this experiences can be put to vs code extensions. This can bridge the user experience from just having installed the toolkit to starting to use the toolkit.
• We can do smooth introduction to critical concepts and mandatory files required by our toolkit.
• This can allow us to navigate users through key features of the toolkit and possibly provide call to actions for users (start new project, hello world app, sample app, etc).

[Eskibear]

It's nice and modern, and this would be really helpful for new users, especially the UI tour part.

And it would be even more helpful if UI tour functionality is exposed to extensions. E.g. In Java extensions, we would be able to point first-time Java users to the right place of their desired features.

(Users are complaining about missing features, and the truth is, we do have the features in vscode but they don't find it...)

[yaojinyang]

Just like Java, I expect more language and extension teams will leverage this design to provide their own onboarding experience. Then, being consistent and not re-inventing the wheel will become important, which underlines the need of exposing the capabilities as standard APIs for other teams to consume.

[miguelsolorio]

👋 Hey everyone, it's been a few months since we last updated and we've made a lot of progress that we wanted to share.

User testing feedback

We ran these concepts through user testing and saw a lot of surprising things. Most users chose to "Skip" the onboarding flows we were testing, and the ones that did click through them didn't read the content. The other issue that came up was that the onboarding only appeared once so users were unable to go back to reference certain sections. So we went back and iterated on the concept to make it much more useful.

Getting started content

Instead of having a temporary experience that users often glossed over (especially when being task focused like opening a folder or creating a file), we wanted a way for this content to be easily accessible at any point. We also wanted to have content that would appeal for all development experiences whether it's for those learning to code or the seasoned developer. That led us down the path of having a dedicated "Get Started" area that could contain all of this content.

In this flow, we are able to define step-by-step instructions w/ animated gifs, and also have tie actions to commands (in the example above, the Pick a theme action is tied to the workbench.action.selectTheme command. The moment the user clicks the action, we'll mark the items as complete and then start showing progress on the main card on the welcome page.

Allowing extensions to contribute

Because this content lives on the welcome page, users can come back to this content at a later time. This also means that we can open this up for extensions to contribute (#116414). This is currently under our proposed api, so if you start contributing to this be aware that it may be unstable until we officially launch this.

Next steps

We've got the architecture setup on Insiders (you can toggle this using the
Help: Getting Started command or changing workbench.startupEditor to gettingStarted in your user settings) but we're still polishing the overall experience. If you're interested in the overall improvements to the welcome page you can subscribe to #63152. This issue will be primarily focused on the Getting Started experience.

[JacksonKearl]

Enabled by default starting today! Please do not hesitate to open new issues for feedback/bug reports/design critique/etc.

[alexr00]

I verified that I could run the "Help: Getting Started" command to open the Getting Started page, then clicked around a bit on that page. I also verified that extensions contributed content showed.

[drazisil]

How do you reset the experience? I deleted my .vscode dir, uninstalled and reinstalled vs code, and It's still mostly completed.

[JacksonKearl]

@drazisil