Create a terminal getting started tutorial

[ntrogh]

Create a getting started tutorial for the terminal experience that guides users through their first steps with the terminal. Provides guided instructions for the key, day-1 functionalities.

[ntrogh]

Outline for tutorial

1. Introduction
   • Overview of terminal
   • What is a shell
2. Run your first command in the terminal
   • Open the terminal (keybinding, menu, ..)
   • Run a command and view output
   • Navigate to files/URLs using links in output
3. Run commands in another shell
   • Add a new terminal
   • Choose different profile
   • View list of terminals
4. Arrange the terminal window
   • Maximize
   • Move into editor, drag into floating window
5. Manage the terminal
   • Change name/color/icon
   • Delete terminal
6. Next steps
   • Basics
   • Profiles
   • Customization

[ntrogh]

@Tyriar Appreciate your feedback on the above outline for the Terminal Getting Started Tutorial.

[Tyriar]

Looks good! Some comments:

---

These parts I think aren't so important and don't meet the cut for being called out imo:

• Maximize
• Change name/color/icon

---

Navigate to files/URLs using links in output

Calling out :line:col support in a file link would be good. Also maybe the fact that pretty much everything can be clicked and it will fallback to a file search like ctrl+p.

---

It would be nice if shell integration was called out somewhere as it is enabled by default. Command navigation in particular is a basic feature that would be good to mention and also has a fallback in case shell integration isn't enabled (so you wouldn't even need to mention "shell integration" in the tutorial).

[ntrogh]

@Tyriar thanks for the feedback. I'll start with a draft and incorporate it.

[ntrogh]

@Tyriar First draft of the getting started: https://github.com/microsoft/vscode-docs/blob/terminal-getting-started/docs/terminal/getting-started.md

[Tyriar]

The integated terminal can run commands like mkdir, ls, and git, just like a standalone terminal.

mkdir is Windows-specific, how about echo instead which works everywhere and is often part of hello world tutorials?

such as links to workspace files or error detection

or -> and?

Examples of shells include Bash, Z shell, and PowerShell.

"Zsh" is more recognizable

[Tyriar]

or by pressing kb(workbench.action.terminal.toggleTerminal) keyboard shortcut.

the ... keyboard shortcut?

Bash, PowerShell, or Command Prompt.

Command Prompt should never be the default, it will almost always be Windows PowerShell, PowerShell (v6+), Bash (typical on Linux) or Zsh (typical on macOS).

Note that the shell starts at the root of the workspace folder.

the shell's working directory starts at....?

Enter a basic command like ls (on macOS and Linux) or dir (on Windows) to list the files in the current directory.

ls works in pwsh so just saying that would make things simpler.

Tip: You can enlarge the terminal by dragging the terminal panel's border or by selecting the chevron up icon to maximize the panel.

It's probably pretty common for people to not know what a chevron is, I couldn't find an upwards chevron unicode char but `(^) would be enough to help the user here.

For example, the compiler or linter might return an error message with a file path and line number.

the compiler -> a compiler

Open the terminal where you previously ran the ls or dir command.

ls

For other text, VS Code opens a Quick Pick that enables you to search for that text across your workspace.

Quick pick is the generic name for the UI component. Maybe re-word to something like this: "For other text, VS Code tries to search the workspace for files containing the text"

If you keep pressing kb(workbench.action.terminal.scrollToPreviousCommand) multiple times

If you press kb(workbench.action.terminal.scrollToPreviousCommand) multiple times?

Depending on which shell you're using, you can see a circle icon in the gutter next to a previously run command.

"you may see"?

Run commands in another shell

This is a good section to mention pulling the tab into an editor

[ntrogh]

Thanks for the detailed feedback already, @Tyriar. Wanted to share early, so I still needed to do my edit pass. Are you ok with overall structure, scenarios, and length of the article?

[Tyriar]

Yep, I like the structure and length