Add a JavaScript Walkthrough

[DanielRosenwasser]

This PR provides a built-in JavaScript walkthrough in Visual Studio Code. I think on some level we believe there's a group of beginners who are likely to stop using Visual Studio Code because they download it and don't know what to do next. Giving a walkthrough provides a clearer path on what those next steps are. So while we originally wanted to do a TypeScript walkthrough, it made more sense to just provide a JavaScript walkthrough, since TypeScript typically involves considering a build step, bundling, and assumes some level of comfort in JavaScript itself.

While we can provide a TypeScript walkthrough in the future, there are ideas in #144062 that will likely simplify the walkthrough as well. In other words, I think that making the built-in experience for VS Code better will make the walkthroughs better too.

Huge thanks to @luabud for laying the foundation on the Python side.

Fixes microsoft/TypeScript#48489
Ticks a box off on #144062

Here's the current TODOs, with some specific callouts that I'd appreciate some input on.

• Media Assets: I'll need to work with @misolori @daviddossett on these.
  • Walkthrough icon
  • Media for each step (currently just a TODO page)
• Workflow and Phrasing
  • Should we recommend a .mjs file or .js file? Leaning towards .js.
  • Should we try to more intentionally tie the HTML file and the loose JS file steps? Seems unclear how we could do this.
  • Can we add a step to teach how to debug (leaning towards no)? Can we easily link to debugging docs if not?
• Polish
  • How do I stylize the text for each of these prompts? I can't seem to use mono-spaced or keyboard-like text for things like <script> or F5 in the walkthrough steps. (@JacksonKearl)
  • Can we either hide or fill in the step for installing Node.js? Is there an easy way to determine whether Node.js is already installed? (@mjbvz)
  • Seems like there's a surprising delay for the Create an HTML file button. Is that just because I'm debugging?
  • In the last step, if a user tries to run/debug a single JavaScript file in their root directory, the debugger takes forever to start. Can we fix this? (@connor4312)
• Experiments: Let's plumb these through (@devinvalenciano @isidorn @digitarald). Good experiments to start with:
  • How do we pitch this? Is it a "get started with JS" or a "get started with HTML and JS" walkthrough?
  • Which sample do we give for HTML? Should we do sample with the current HTML file vs. one with a prompt()/alert()?

[tuckstarrydell]

commit #151663 # # # # # # @ @DanielRosenwasser

[daviddossett]

Cool to see this! Here's some real-time feedback as I step through the walkthrough. I won't nitpick on copy, icons, etc. for now:

Step 1

My first reaction was that the created HTML file was way more "complete" than I would have expected. My assumption is that there wouldn't be any JavaScript written yet, and that I'd do it myself at a later step.

Step 2

• "View Your Web Page" seems very reasonable, but "Start Debugging" feels intimidating through a novice lens. How important is the debugging concept at this stage? Could it be something more outcome-focused like "Open in your browser" or "Debug in your browser"?
• I don't have Chrome installed, but it was still available as a debugger suggestion @roblourens is there anything we can do to curate that list?
• The step wasn't marked as completed once I'd chosen a environment. I think the same was true for step 1, too.

Step 3

Not sure at this point why I need node since I was just in the browser. Is there an outcome we can use instead? Makes sense to hide this if Node is already installed. Seems reasonable to link to the page, in any case.

Step 4

It took me a second to realize this was sort of a different task altogether. I originally thought I'd be creating a new .js file to further interact with the HTML page. Seems like this about just running a standalone file, unrelated to the first half of the walkthrough.

Reading the step's description again, it seems like that's made somewhat clear at the end. But it still could be easily read as creating a new file to link to in the HTML file via a script tag. And many people won't read the description 😉

Overall thoughts

Now that I've been through it, a couple of high-level thoughts come to mind:

• As a user, it seemed like the walkthrough was framed as if I was going to be actually writing some HTML and JS as part of the walkthrough. Instead, it's more about opening/running previously-written code. I think that's fine, but how could we frame the walkthrough to better convey that?
• Should the standalone JS section be in it's own walkthrough as a follow up? Perhaps both the JS-in-HTML and standalone JS flows could then be slightly expanded to have users do more—like writing a bit of hello world-style JS vs. having it done for them.

Excited for this!

[roblourens]

@daviddossett are you talking about the old "Debugger for Chrome" extension? That is marked as deprecated in the marketplace now, where do you see it?

[roblourens]

Or maybe you just saw the "Web app (Chrome)" entry in the debugger list, checking for a chrome install before including that could be a js-debug feature request

[daviddossett]

Or maybe you just saw the "Web app (Chrome)" entry in the debugger list, checking for a chrome install before including that could be a js-debug feature request

Yeah it was this. I ended up getting an error since I wasn't thinking and just hit enter. I'll file an issue.

[isidorn]

@DanielRosenwasser great work, I think this will be a great addition to the getting started page!
+1 for @daviddossett comments. Apart from that, here's some feedback.

1. I see some minor compile errors
   
2. I suggest to use VS Code, and not Visual Studio Code to align with other walkthroughs
   
3. Agree with @daviddossett that it would be nice to have more distinct separation between HTML and node flow. Should these be two different walkthroughs?
4. Can we use when context to detect if node is installed, and if yes do not show the step "install nodejs"
5. I am leaning towards .js, and not complicating the life of beginners with .mjs

I plan to provide more feedback next week, so we do not drown you in feedback on day 1 :)
Also you could demo this in VS Code UX sync. Or let me know if you want me to share this to the broader VS Code team once you would like to get more feedback.

Thanks a lot for working on this!

fyi @connor4312 @weinand for debugging ideas
fyi @luabud for potential ideas from Python walkthrough

[DanielRosenwasser]

@daviddossett thank you for the feedback!

My first reaction was that the created HTML file was way more "complete" than I would have expected. My assumption is that there wouldn't be any JavaScript written yet, and that I'd do it myself at a later step.

This is possibly something we can condition with an experiment - but I do think we should have some JS that does something basic like setting text on an HTML element (e.g. output.textContent = "hello world!"; or even alert()).

How important is the debugging concept at this stage? Could it be something more outcome-focused like "Open in your browser" or "Debug in your browser"?

Yeah, I 100% agree - debugging is not what I care about at this point, and all I'm trying to do is make it easy to view the web page. 😅

I went back and forth on this because I wasn't sure how much we should teach and when. We're going to tell people "Hit F5 to run!", but then at some point they'll learn that it's actually debugging - and maybe that's okay?

In that case, should I not have the button focus on the debug output pane?

The step wasn't marked as completed once I'd chosen a environment. I think the same was true for step 1, too.

Weird, I'll double check this.

Not sure at this point why I need node since I was just in the browser.

Huh, I think the intent for this walkthrough was to not surface this as an option in the browser. What kind of environment were you in?

Should the standalone JS section be in it's own walkthrough as a follow up? Perhaps both the JS-in-HTML and standalone JS flows could then be slightly expanded to have users do more—like writing a bit of hello world-style JS vs. having it done for them.

@chrisdias suggested this too. I'm happy to rethink this tutorial as a way to start building web pages in Visual Studio Code. For example:

1. Start with HTML and view that.
2. Hit F5 to view it.
3. Add some CSS in the <head> element to style it
4. Add a <script> tag after the </body> (uh maybe bad practice but 🤷‍♂️) to add some JS
5. Extract the CSS and JS into a <link> and <script src="...">

But it might take some time to get that going.

[DanielRosenwasser]

@isidorn

I see some minor compile errors

Weird, those seem to say that an import to vscode is not included. Did you need to re-run yarn or something from your workspace?

I am leaning towards .js, and not complicating the life of beginners with .mjs

👍🏻