Standardize docs formatting (#233)

* locals

* move links to bottom

* fix numbering discrepency; standardize table

* no need for **

* spacing

* put back single-use internal links

.github/CONTRIBUTING.md

@@ -1,8 +1,12 @@
 # Contributing
 
-See [Contributing Guide](../Documentation/contributing.md) for information about:
+See [Contributing Guide][contributing] for information about:
 
 * Which kind of PRs we accept/reject for .NET Core 3.0 release
 * Coding style
 * PR style preferences (squashing vs. merging, etc.)
 * Developer guide for building and testing locally
+
+[comment]: <> (Links)
+
+[contributing]: ../Documentation/contributing.md

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "cSpell.words": [
+        "binlog",
+        "repos",
+        "winforms"
+    ]
+}

CODE_OF_CONDUCT.md

@@ -2,4 +2,8 @@
 
 This project has adopted the code of conduct defined by the Contributor Covenant
 to clarify expected behavior in our community.
-For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).
+For more information, see the [.NET Foundation Code of Conduct][dotnet-code-of-conduct].
+
+[comment]: <> (URI Links)
+
+[dotnet-code-of-conduct]: https://dotnetfoundation.org/code-of-conduct

Documentation/building.md

@@ -1,39 +1,52 @@
 # Building Windows Forms
 
 ## Prerequisites
-Follow the prerequisites listed at [Building CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md)
+
+Follow the prerequisites listed at [Building CoreFX on Windows][corefx-windows-instructions]
 
 ## Building from the command line
-* Run `.\build` from the repo root.
+
+* Run `.\build` from the repository root.
   * Builds the `System.Windows.Forms.sln` using the default config (Debug|Any CPU)
 * To specify a config, add `-configuration` followed by the config such as `.\build -configuration Release`
 
 If your build is successful, you should see something like this:
+
 ```console
 Build succeeded.
     0 Warning(s)
     0 Error(s)
 ```
 
-Note that this does **not** build using your machine-wide installed version of the dotnet sdk. It builds using the dotnet sdk specified in the global.json in the repo root.
+Note that this does **not** build using your machine-wide installed version of the dotnet sdk. It builds using the dotnet sdk specified in the global.json in the repository root.
 
 ## Building from Visual Studio
+
 * To build from Visual Studio, open System.Windows.Forms.sln in Visual Studio and build how you normally would.
 * Visual Studio behaves slightly differently than the command line. It uses the machine-wide installed SDK instead of the one specified in the global.json.
-  * Please make sure you have the [latest .Net Core Daily Build](https://github.com/dotnet/core/blob/master/daily-builds.md) installed.
+  * Please make sure you have the [latest .Net Core Daily Build][latest-core-build] installed.
 
 ## Build outputs
+
 * All build outputs are generated under the `artifacts` folder.
 * Binaries are under `artifacts\bin`
   * For example, `System.Windows.Forms.dll` can be found under `artifacts\bin\System.Windows.Forms\Debug\netcoreapp3.0`
 * Logs are found under `artifacts\log`
 * Packages are found under `artifacts\packages`
 
 ## Troubleshooting build errors
+
 * Most build errors are compile errors and can be dealt with accordingly.
 * Other error may be from MSBuild tasks. You need to examine the build logs to investigate.
   * The logs are generated at `artifacts\log\Debug\Build.binlog`
-  * The file format is an MSBuild Binary Log. Install the [MSBuild Structured Log Viewer](http://msbuildlog.com/) to view them.
+  * The file format is an MSBuild Binary Log. Install the [MSBuild Structured Log Viewer][msbuild-log-viewer] to view them.
 
 ## Creating a package
-To create the Microsoft.Private.Winforms package, run `.\build -pack`
+
+To create the Microsoft.Private.Winforms package, run `.\build -pack`
+
+[comment]: <> (URI Links)
+
+[corefx-windows-instructions]: https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md
+[latest-core-build]: https://github.com/dotnet/core/blob/master/daily-builds.md
+[msbuild-log-viewer]: http://msbuildlog.com/

Documentation/contributing.md

@@ -1,17 +1,17 @@
 # Contributing Guide
 
-The primary focus of .NET Core 3.0 release for Windows Forms is to achieve parity with .NET Framework. Priority will be given to changes that align with that goal. See the [roadmap](../roadmap.md) to understand project goals.
+The primary focus of .NET Core 3.0 release for Windows Forms is to achieve parity with .NET Framework. Priority will be given to changes that align with that goal. See the [roadmap](roadmap.md) to understand project goals.
 
 We need the most help with the following types of changes:
 
-* Test fixes, test improvements and new tests increasing code coverage.
+* Test fixes, test improvements, and new tests increasing code coverage.
 * Bug fixes that specifically target parity between .NET Core and .NET Framework.
 
-Please [file an issue](https://github.com/dotnet/winforms/issues) for any larger change you would like to propose.
+Please [file an issue][issues] for any larger change you would like to propose.
 
-See [Developer Guide](developer-guide.md) to learn how to develop changes for this repo.
+See [Developer Guide](developer-guide.md) to learn how to develop changes for this repository.
 
-This project follows the general [.NET Core Contribution Guidelines](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/contributing.md). Please read it before submitting PRs.
+This project follows the general [.NET Core Contribution Guidelines][corefx-contribution-guidelines]. Please read it before submitting PRs.
 
 The contribution bar from the general contribution guidelines is copied below.
 
@@ -24,3 +24,8 @@ Maintainers will not merge changes that have narrowly-defined benefits due to co
 Most .NET Core components are cross-platform and we appreciate contributions that either improve their feature set in a given environment or that add support for a new environment. We will typically not accept contributions that implement support for an OS-specific technology on another operating system. For example, we do not intend to create an implementation of the Windows registry for Linux or an implementation of the macOS keychain for Windows. We also do not intend to accept contributions that provide cross-platform implementations for Windows Forms or WPF.
 
 Contributions must also satisfy the other published guidelines defined in this document.
+
+[comment]: <> (URI Links)
+
+[issues]: https://github.com/dotnet/winforms/issues
+[corefx-contribution-guidelines]: https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/contributing.md

Documentation/debugging.md

@@ -1,35 +1,40 @@
 # Debugging
 
-There are two recommended ways to debug Windows Forms binaries. Both require that you first [build from source](https://github.com/dotnet/corefx/blob/master/Documentation/building.md).
+There are two recommended ways to debug Windows Forms binaries. Both require that you first [build from source][corefx-building].
 
 Then, you are free make your changes locally.
 
 Once you are ready to debug your changes on an existing Windows Forms application, please follow one of the two following recommended techniques for relating your changes back to your project. You should then be able to set breakpoints and debug as expected.
 
 If you do not want to modify your local SDK, you may with to perform technique 2, while if you do not want to add an additional reference to your project, technique 1 may be better for you.
 
-### 1. Copy your changes into the SDK
+## (1) Copy your changes into the SDK
 
 copy the resulting assembly(-ies) from the base of the repository  
 
-`[path-to-repo]\winforms\artifacts\bin\System.Windows.Forms\Debug\netcoreapp3.0_ `
+`[path-to-repo]\winforms\artifacts\bin\System.Windows.Forms\Debug\netcoreapp3.0_`
 
 to your dotnet folder at:  
 
 `[Drive]:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App\[Version]`
 
-where **[Drive]** is your OS drive (for example, C:) and and **path-to-repo** is the additional path to our repository from the base drive. **[Version]** is your DesktopUI version directory (for example, 3.0.0-alpha-27017-4). Note if you have Microsoft.DesktopUI.App instead of Microsoft.WindowsDesktop.App, this is the outdated version.
+where **[Drive]** is your OS drive (for example, C:)  and **[path-to-repo]** is the additional path to our repository from the base drive. **[Version]** is your DesktopUI version directory (for example, 3.0.0-alpha-27017-4). Note if you have Microsoft.DesktopUI.App instead of Microsoft.WindowsDesktop.App, this is the outdated version.
 
-**NOTE** that this will modify your SDK; to revert back, you will have to repair the install or reinstall. See the [dotnet Core repository](https://github.com/dotnet/core) for more information.
+**NOTE** that this will modify your SDK; to revert back, you will have to repair the install or reinstall. See the [dotnet Core repository][dotnet-core-repos] for more information.
 
-### 2. Point your project to your experimental binary(-ies)
+## (2) Point your project to your experimental binary(-ies)
 
 Add references to the binary(-ies) to your project ported to Core. For example, for System.Windows.Forms, you should add the following reference:
 
 ```xml
 <ItemGroup>
-    <Reference Include="[Drive]:[path-to-repo]\winforms\artifacts\bin\System.Windows.Forms\Debug\netcoreapp3.0\System.Windows.Forms.dll" />   
+    <Reference Include="[Drive]:[path-to-repo]\winforms\artifacts\bin\System.Windows.Forms\Debug\netcoreapp3.0\System.Windows.Forms.dll" />
 </ItemGroup>
 ```
 
-where **[Drive]** is the drive you have our repository in and **path-to-repo** is the additional path to our repository from the base drive (this may be nothing). Note netcoreapp3.0 may change.
+where **[Drive]** is the drive you have our repository in and **[path-to-repo]** is the additional path to our repository from the base drive (this may be nothing). Note netcoreapp3.0 may change.
+
+[comment]: <> (URI Links)
+
+[corefx-building]: https://github.com/dotnet/corefx/blob/master/Documentation/building.md
+[dotnet-core-repos]: https://github.com/dotnet/core

Documentation/developer-guide.md

@@ -1,12 +1,12 @@
 # Developer Guide
 
-The following document describes the setup and workflow that is recommended for working on the Windows Forms project. It assumes that you have read the [contributing doc](contributing.md).
+The following document describes the setup and workflow that is recommended for working on the Windows Forms project. It assumes that you have read the [Contributing Document](contributing.md).
 
 The [Issue Guide](issue-guide.md) describes our approach to using GitHub issues.
 
 ## Machine Setup
 
-Follow the [Building CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md) instructions.
+Follow the [Building CoreFX on Windows][corefx-windows-instructions] instructions. However, we recommend Visual Studio 2019 Preview 1.
 
 Windows Forms requires the following workloads and components be selected when installing Visual Studio:
 
@@ -19,17 +19,29 @@ Windows Forms requires the following workloads and components be selected when i
 
 ## Workflow
 
-We use the following workflow for building and testing features and fixes.
+We use the following workflow for building as well as testing features and fixes.
 
-You first need to [Fork](https://github.com/dotnet/corefx/wiki/Checking-out-the-code-repository#fork-the-repository) and [Clone](https://github.com/dotnet/corefx/wiki/Checking-out-the-code-repository#clone-the-repository) this WinForms repository. This is a one-time task.
+You first need to [Fork][fork] and [Clone][clone] this WinForms repository. This is a one-time task.
+
+1. [Build](building.md) the repository.
 
-1. [Build](building.md) the repo.
 2. [Debug](debugging.md) the change, as needed.
-3. [Test](testing.md) the change, to validate quality.
+
+3. [Test](testing.md)the change, to validate quality.
 
 ## More Information
 
-* [Git commands and workflow](https://github.com/dotnet/corefx/wiki/git-reference)
-* [Coding guidelines](https://github.com/dotnet/corefx/tree/master/Documentation#coding-guidelines)
-* [up-for-grabs WinForms issues](https://github.com/dotnet/winforms/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
-* [easy WinForms issues](https://github.com/dotnet/winforms/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Aeasy)
+* [Git commands and workflow][git-commands]
+* [Coding guidelines][corefx-coding-guidelines]
+* [up-for-grabs WinForms issues][up-for-grabs]
+* [easy WinForms issues][easy]
+
+[comment]: <> (URI Links)
+
+[corefx-windows-instructions]: https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md
+[fork]: https://github.com/dotnet/corefx/wiki/Checking-out-the-code-repository#fork-the-repository
+[clone]: https://github.com/dotnet/corefx/wiki/Checking-out-the-code-repository#clone-the-repository
+[git-commands]: https://github.com/dotnet/corefx/wiki/git-reference
+[corefx-coding-guidelines]: https://github.com/dotnet/corefx/tree/master/Documentation#coding-guidelines
+[up-for-grabs]: https://github.com/dotnet/winforms/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs
+[easy]: https://github.com/dotnet/winforms/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Aeasy

Documentation/getting-started.md

@@ -6,8 +6,9 @@ This document describes the experience of using WinForms on .NET Core. The [Deve
 
 Choose one of these options:
 
-1. [.NET Core 3.0 SDK Preview 1 (recommended)](https://www.microsoft.com/net/download)
-2. [.NET Core 3.0 daily build (latest changes, but less stable)](https://github.com/dotnet/core/blob/master/daily-builds.md)
+1. [.NET Core 3.0 SDK Preview 1 (recommended)][.net-core-3.0-sdk-preview-1]
+
+1. [.NET Core 3.0 daily build (latest changes, but less stable)][.net-core-3.0-daily]
 
 ## Creating new applications
 
@@ -25,8 +26,14 @@ WinForms Core does not yet have a dedicated Designer tool. For the time being, y
 
 ## Samples
 
-Check out the [.NET Core 3.0 WinForms samples](https://github.com/dotnet/samples/tree/master/windowsforms) for both basic and advanced scenarios.
+Check out the [.NET Core 3.0 WinForms samples][.net-core-3.0-samples] for both basic and advanced scenarios.
 
 ## Porting existing applications
 
 To port your existing WinForms application from .NET Framework to .NET Core 3.0, refer to our [porting guidelines](porting-guidelines.md).
+
+[comment]: <> (URI Links)
+
+[.net-core-3.0-sdk-preview-1]: https://www.microsoft.com/net/download
+[.net-core-3.0-daily]: https://github.com/dotnet/core/blob/master/daily-builds.md
+[.net-core-3.0-samples]: https://github.com/dotnet/samples/tree/master/windowsforms