Merge pull request #415 from AvaloniaUI/issue-413

Rework Get Started for accuracy

Author: MikeCodesDotNET

docs/get-started/getting-started.md

@@ -1,4 +1,4 @@
-s---
+---
 id: getting-started
 title: Starting with the CLI
 ---

docs/get-started/install.md

@@ -3,11 +3,16 @@ id: install
 title: Install
 ---
 
+## Preinstallation
+
+Please start with the supported IDE of your choice installed. Avalonia supports Visual Studio, Rider, and Visual Studio 
+Code.
+
 ## Install Avalonia UI Templates
 
-The best place to get started with Avalonia is by creating an application using a template.
+The best way to get started with Avalonia is by creating an application using a project template.
 
-To install the Avalonia templates, run the following command:
+To install the [Avalonia templates](https://github.com/AvaloniaUI/avalonia-dotnet-templates), run the following command:
 
 ```bash
 dotnet new install Avalonia.Templates
@@ -36,4 +41,56 @@ Avalonia Styles                               avalonia.styles
 Avalonia TemplatedControl                     avalonia.templatedcontrol   [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
 Avalonia UserControl                          avalonia.usercontrol        [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
 Avalonia Window                               avalonia.window             [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
-```
+```
+
+## Create a new Application
+
+Once the project templates are installed, you can create a new _Avalonia UI_ application from CLI by running the following command:
+
+```bash
+dotnet new avalonia.app -o MyApp
+```
+
+This will create a new folder called `MyApp` containing your application files. To run the application, navigate to the `MyApp` folder and run:
+
+```bash
+cd MyApp
+dotnet run
+```
+
+The project templates will also allow for project creation from your IDE.
+
+## Installation Troubleshooting
+
+### Ensure .NET SDK is installed
+
+```
+dotnet --list-sdks
+
+8.0.202 [C:\Program Files\dotnet\sdk] <-- Your version may vary
+```
+
+If `dotnet` is not a recognized program, then ensure you've installed your IDE first. Next, ensure that `dotnet` is 
+associated with the terminal. On Windows, this involves checking environment variables: `echo %PATH%` in the command prompt or 
+`echo $Env:PATH` in PowerShell.
+
+### Ensure NuGet source is correct
+
+If while installing the project templates, you receive an error stating the `Avalonia.Templates` package cannot be found, 
+then ensure NuGet is correctly setup with .NET's standard global package source.
+
+```
+dotnet nuget list source
+
+Registered Sources:
+  1.  nuget.org [Enabled]
+      https://api.nuget.org/v3/index.json
+```
+
+If this source is not listed, add it:
+
+```
+dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
+```
+
+If the package install still fails despite NuGet being listed, then suspect a network connectivity or firewall issue.

docs/get-started/set-up-an-editor.md

@@ -8,23 +8,26 @@ import AvaloniaVsExtensionNuGetScreenshot from '/img/get-started/avalonia-vs-ext
 
 # Set Up an Editor
 
-You can create an Avalonia application using any code editor, but using an IDE will give you support for authoring Avalonia XAML files with a previewer and code completion.
+You can create an Avalonia application using any code editor, but using an IDE will give you support for authoring 
+Avalonia XAML files with a previewer and code completion.
 
 ## JetBrains Rider
 
-The [JetBrains Rider](https://www.jetbrains.com/rider/) IDE has built-in support for Avalonia XAML [starting in 2020.3](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) including first-class support for Avalonia-specific XAML features and custom code inspections.
+The [JetBrains Rider](https://www.jetbrains.com/rider/) IDE has built-in support for Avalonia XAML [starting in 2020.3](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) including first-class 
+support for Avalonia-specific XAML features and custom code inspections.
 
 See the [JetBrains Rider 2020.3 release announcement](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) for more information.
 
-Rider does not yet provide a visual designer, but this is in development. See [the GitHub project](https://github.com/ForNeVeR/AvaloniaRider) for more information and instructions on how to install.
+Rider does not yet provide a visual designer, but this is in development. See [the GitHub project](https://github.com/ForNeVeR/AvaloniaRider) for more 
+information and instructions on how to install.
 
 ## Visual Studio
 
 If you're developing Avalonia with Visual Studio you should install the [Avalonia for Visual Studio](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS) extension.
 
 <img className="center" src={AvaloniaVsExtensionMarketplaceScreenshot} alt="" />
 
-The extension provides intellisense support for Avalonia XAML together with a previewer.
+The extension provides IntelliSense support for Avalonia XAML together with a previewer.
 
 To install the Avalonia for Visual Studio extension:
 

docs/get-started/test-drive/add-a-control.md

@@ -7,34 +7,38 @@ import Highlight from '@site/src/components/Highlight';
 import CalculateButton from '/img/get-started/test-drive/calculate-button.png';
 import ButtonIntellisenseScreenshot from '/img/get-started/test-drive/button-intellisense.png';
 
-So far the main window of your application displays only a text string. On this page, you will learn how to add some of the built-in controls that are part of Avalonia.
+So far, the main window of your application displays only a text string. On this page, you will learn how to add some of the built-in controls that are part of Avalonia.
 
 ## Button
 
-Avalonia contains a built-in control that creates a button. Follow this procedure to replace the text string you currently have in the content zone of the window, with a button control.
+Avalonia contains a built-in control that creates a button. Follow this procedure to replace the text string currently in the `Window`'s content zone with a button control.
 
 - Stop the app if it is running.
 - Locate the 
 `<TextBlock Text="text" HorizontalAlignment="Center" VerticalAlignment="Center"/>`	
 in the `MainView.axaml` file.. 
 - Delete the entire line.
-- Insert a 'Button' tag as shown:
+- Insert a `Button` tag as shown:
 ```xml
   <Button>Calculate</Button>
 ```
 <img className="center" src={CalculateButton} alt="" />
 
 :::tip
-If you're using a previewer, you will see the button appear in the preview pane as soon as the XAML is valid. You can also try out a mouse move-over and click on the button to see the different colors it displays in different states.
+If you're using the previewer, you will see the button appear in the preview pane as soon as the XAML is valid. You can 
+also try hovering and clicking the `Button` to see it change appearance in different states.
 :::
 
 - Run the app to confirm that the presentation and behaviour of the button is the same at runtime.
 
 ## Control Attributes
 
-The XAML code for Avalonia controls uses attributes to specify presentation and behaviour. The attributes can set properties, call methods and event handlers in the controls created by the XAML.
+XAML uses XML attributes to specify presentation and behavior for controls. These attributes can set properties, call 
+methods, and call event handlers in the controls created by the XAML.
 
-For example, you  will notice that the button you just implemented is rendered hard against the left edge of the window. This is a result of the default value of its horizontal alignment property (which is left). Follow this procedure to set the horizontal alignment to centered instead.
+For example, the `Button` is currently positioned hard against the left edge of the `Window`. This is a result 
+of the default value (left) of its `HorizontalAlignment` property. Follow this 
+procedure to set the `HorizontalAlignment` to centered instead.
 
 - Add a new attribute to the Button tag as follows:
 
@@ -43,12 +47,13 @@ For example, you  will notice that the button you just implemented is rendered h
 ```
 
 :::tip
-If you're using an IDE, notice how the Avalonia Intellisense guides you as you add attributes to the XAML.
+If you're using an IDE, notice how the Avalonia code completion guides you as you add attributes to the XAML.
 
 <img className="center" src={ButtonIntellisenseScreenshot} alt="" />
 :::
 
-The button should now move to the center of the window content zone (both horizontally and vertically).
+The `Button` should now move to the center of the window content zone. Horizontally because of the change and vertically 
+because of the Button's default.
 
 :::info
 For full information about the complete range of Avalonia UI built-in controls, and their attributes, see the reference section [here](../../reference/controls).

docs/get-started/test-drive/add-some-layout.md

@@ -6,15 +6,18 @@ title: Add Some Layout
 import StackPanelZonesDiagram from '/img/get-started/test-drive/stackpanel-zones.png';
 import TemperatureStackPanelScreenshot from '/img/get-started/test-drive/temperature-stackpanel.png';
 
-Avalonia provides a range of built-in controls to help you layout the visual elements of an application. On this page you will see how to use some of these layout controls.
+Avalonia provides a range of built-in controls to help you layout the visual elements of an application. On this page, 
+you will see how to use some of these layout controls.
 
 At this stage, your application has a single button located in the content zone of the main window.
 
-In fact an Avalonia window allows only a single other control in its content zone. So to add the multiple visual elements required for most applications, you will need to use one of the built-in layout controls that allows multiple other controls inside its content zone.
+In fact, an Avalonia `Window` allows only one control in its content zone. To show multiple visual elements, you 
+must use a layout control that allows multiple controls within its content zone.
 
-## Stack Panel
+## StackPanel
 
-The stack panel control allows multiple controls in its content zone, and arranges them in a vertical stack in the sequence they are defined in the XAML.
+The `StackPanel` control lays out a sequence of controls in the order they are defined in XAML. By default, it lays out 
+in a vertical stack but this can be changed to horizontal with its `Orientation` property.
 
 <img src={StackPanelZonesDiagram} alt="" />
 
@@ -25,33 +28,30 @@ The stack panel control allows multiple controls in its content zone, and arrang
 </StackPanel>
 ```
 
-## Text Block
+## TextBlock
 
-The text block control gives you full control over the styling of the text it contains.
+The `TextBlock` control allows extensive styling of its contained text.
 
-To take the example forwards, add a stack panel as follows (you can include the existing the button XAML).
+To take the example forward, add a `StackPanel` as follows (include the preexisting `Button` XAML):
 
 ```xml
 <StackPanel>
-    <Border Margin="5" 
-      CornerRadius="10"
-      Background="LightBlue">
-      <TextBlock Margin="5"
-         FontSize="24" 
-         HorizontalAlignment="Center"
-         Text="Temperature Converter">
-      </TextBlock>
+    <Border Margin="5" CornerRadius="10" Background="LightBlue">
+        <TextBlock Margin="5"
+            FontSize="24" 
+            HorizontalAlignment="Center"
+            Text="Temperature Converter">
+        </TextBlock>
     </Border>
-    <StackPanel>
-    </StackPanel>    
+
     <Button HorizontalAlignment="Center">Calculate</Button>
-  </StackPanel>
+</StackPanel>
 ```
 
 <img className="center" src={TemperatureStackPanelScreenshot} alt="" />
 
 :::info
-You can explore the other layout controls in Avalonia from the reference [here](../../reference/controls/layout-controls.md).
+You can explore the other layout controls in Avalonia using the reference [here](../../reference/controls/layout-controls.md).
 :::
 
 On the next page, you will add some inputs to the middle of the window.

docs/get-started/test-drive/code-with-controls.md

@@ -3,19 +3,18 @@ id: code-with-controls
 title: Code With Controls
 ---
 
-import Highlight from '@site/src/components/Highlight';
-
-The action you will implement here is to update the Fahrenheit temperature control, using the value of the `celsius` control, and a simple formula, whenever the button is clicked.
+In this section, you will implement the core logic to update the Fahrenheit temperature based on the Celsius input.
 
 ## Control Names
 
-When Avalonia creates the main window at runtime, it also creates objects for each of the controls defined in the window. Your code can access the controls at runtime, but to access them, it will need some control names.
+Avalonia creates objects for each control defined in the XAML hierarchy. Your code can access these controls at runtime, 
+but should be named for easy access.
 
-To add some control names, follow this procedure:
+To add control names, follow this procedure:
 
 - Stop the app if it is running.
 - Locate the `TextBox` for Celsius.
-- Add the name attribute like this:
+- Add the `Name` attribute like this:
 
 ```xml
 <TextBox ... Name="celsius"/>
@@ -27,11 +26,11 @@ To add some control names, follow this procedure:
 <TextBox ... Name="fahrenheit"/>
 ```
 
-## Get Control Values in Code-behind 
+## Get Control Values in Code-Behind 
 
-To demonstrate access to the text value of the `celsius` input, follow this procedure:
+To access the `Text` value of the `celsius` input, follow this procedure:
 
-- Switch to the **MainWindow.axaml.cs** code-behind file.
+- Switch to the **MainView.axaml.cs** code-behind file.
 - Locate the `ButtonClicked` event handler.
 - Alter the `Debug` statement to display the text property of the `celsius` input, like this:
 
@@ -41,9 +40,10 @@ Debug.WriteLine($"Click! Celsius={celsius.Text}");
 
 - Run the app to confirm that you can see the value in the Celsius appear in the debug window.
 
-## Set Control Values in Code-behind 
+## Set Control Values in Code-Behind 
 
-To use the simple formula that converts Celsius temperature to Fahrenheit, you will first need to ensure that the Celsius input text converts to a number. The formula is then:
+To use the simple formula that converts Celsius temperature to Fahrenheit, you will first need to ensure that the 
+Celsius input text converts to a number. The formula is then:
 
 ```
 Tf = Tc * (9/5) + 32
@@ -52,43 +52,47 @@ Tf = Tc * (9/5) + 32
 To add the conversion formula, follow this procedure:
 
 - Locate the `ButtonClicked` event handler.
-- Alter the code in the event handler to check that the Celsius input text converts to a number.
-- Alter the code to include the conversion formula.
-- Update the text in the Fahrenheit input to the result of the conversion formula.
+- Validate the Celsius input text as a number.
+- Use the conversion formula.
+- Update the `Text` in the Fahrenheit input.
 - Run the app to check your work.
 
 One implementation of the above is as follows:
 
 ```csharp
-if (Double.TryParse(celsius.Text, out double C))
-{
-    var F = C * (9d / 5d) + 32;
-    fahrenheit.Text = F.ToString("0.0");
-}
-else
+public void ButtonClicked(object source, RoutedEventArgs args)
 {
-    celsius.Text = "0";
-    fahrenheit.Text = "0";
+    if (Double.TryParse(celsius.Text, out double C))
+    {
+        var F = C * (9d / 5d) + 32;
+        fahrenheit.Text = F.ToString("0.0");
+    }
+    else
+    {
+        celsius.Text = "0";
+        fahrenheit.Text = "0";
+    }
 }
 ```
 
 You can check your work using the following conversion table:
 
-| Celsius | Farenheit |
-| ---------- | --------- |
-| -10        | 14.0      |
-| 0          | 32.0      |
-| 10         | 50.0      |
-| 21         | 69.8      |
-| 25         | 77.0      |
-| 32         | 89.6      |
+| Celsius | Fahrenheit |
+|---------|------------|
+| -10     | 14.0       |
+| 0       | 32.0       |
+| 10      | 50.0       |
+| 21      | 69.8       |
+| 25      | 77.0       |
+| 32      | 89.6       |
 
 ### Exercises
 
-- You have now used an event handler to get and set control properties at runtime. You could now try some of these exercises:
+You have now used an event handler to get and set control properties at runtime. Try some of these exercises:
+
 - Stop showing the gridlines (easy).
-- Stop the user changing the text in the Fahrenheit input by setting the `IsReadOnly` attribute (easy).
-- Calculate the conversion as the user types into the Celsius input (moderate).
+- Stop the user from changing the text in the Fahrenheit input by setting the `IsReadOnly` attribute (easy).
+- Calculate the conversion as the user types into the Celsius input using the `TextChanged` event (moderate).
 
 :::info
 For full information about the complete range of Avalonia built-in controls, events and attributes, see the controls reference section [here](../../reference/controls/).

docs/get-started/test-drive/create-a-project.md

@@ -25,7 +25,7 @@ dotnet new install Avalonia.Templates
 
 To get started, we're going to use the MVVM Avalonia template: `Avalonia MVVM Application` (or `avalonia.mvvm` in the CLI).
 
-<Tabs>
+<Tabs groupId="ide">
   <TabItem value="cli" label="Command Line" default>
 Run the command:
 
@@ -75,7 +75,7 @@ The template will create a new solution and two new projects. `GetStartedApp` is
 
 We're now ready to run the project!
 
-<Tabs>
+<Tabs groupId="ide">
   <TabItem value="cli" label="Command Line" default>
 Go into the `GetStartedApp` directory and run: