From bc6570eb675d3aa2a6b6e64edf3d66c3eb374d84 Mon Sep 17 00:00:00 2001
From: Tim Abbott <tabbott@zulip.com>
Date: Tue, 13 Apr 2021 21:29:13 -0700
Subject: [PATCH] docs: Update recommendations of Windows installation methods.

This change attempts to highlight WSL 2 as the default installation
method for Windows; that is currently much more reliable than Vagrant.

Further work is probably needed to complete this transition.
---
 docs/development/overview.md       |  2 +-
 docs/development/setup-advanced.md | 18 ++++++++++--------
 docs/development/setup-vagrant.md  |  2 +-
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/development/overview.md b/docs/development/overview.md
index 6e9347851f..3db8c727ac 100644
--- a/docs/development/overview.md
+++ b/docs/development/overview.md
@@ -81,4 +81,4 @@ machine, take a look at our tips for
 [using-dev-env]: using.md
 [testing]: ../testing/testing.md
 [ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork
-[install-via-wsl]: ../development/setup-advanced.html#installing-directly-on-windows-10-experimental
+[install-via-wsl]: ../development/setup-advanced.html#installing-directly-on-windows-10-with-wsl-2
diff --git a/docs/development/setup-advanced.md b/docs/development/setup-advanced.md
index 77554cca0a..bb83aa137a 100644
--- a/docs/development/setup-advanced.md
+++ b/docs/development/setup-advanced.md
@@ -3,7 +3,7 @@
 Contents:
 
 * [Installing directly on Ubuntu, Debian, CentOS, or Fedora](#installing-directly-on-ubuntu-debian-centos-or-fedora)
-* [Installing directly on Windows 10](#installing-directly-on-windows-10-experimental)
+* [Installing directly on Windows 10 with WSL 2](#installing-directly-on-windows-10-with-wsl-2)
 * [Using the Vagrant Hyper-V provider on Windows](#using-the-vagrant-hyper-v-provider-on-windows-beta)
 * [Newer versions of supported platforms](#newer-versions-of-supported-platforms)
 * [Installing directly on cloud9](#installing-on-cloud9)
@@ -57,19 +57,17 @@ on using the Zulip development
 environment](../development/setup-vagrant.html#step-4-developing),
 ignoring the parts about `vagrant` (since you're not using it).
 
-## Installing directly on Windows 10 (experimental)
+## Installing directly on Windows 10 with WSL 2
 
-We will be using Microsoft's new feature [WSL
-2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about) for
-installation.
-
-WSL 2 can be uninstalled by following the instructions [here from Microsoft](https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution-).
+Zulip's development environment is most easily setup on Windows using
+the [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about)
+installation method described here.
 
 1. Install WSL 2 by following the instructions provided by Microsoft
 [here](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install).
 
 1. Install the `Ubuntu 18.04` Linux distribution from the Microsoft
-Store.
+   Store.
 
 1. Launch the `Ubuntu 18.04` shell and run the following commands:
 
@@ -139,6 +137,10 @@ Store.
    environment](../development/setup-vagrant.html#step-4-developing),
    ignoring the parts about `vagrant` (since you're not using it).
 
+WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]
+
+[uninstall-wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution-
+
 ## Using the Vagrant Hyper-V provider on Windows (beta)
 
 You should have [Vagrant](https://www.vagrantup.com/downloads) and
diff --git a/docs/development/setup-vagrant.md b/docs/development/setup-vagrant.md
index 12dadaa87c..ba0eb7d001 100644
--- a/docs/development/setup-vagrant.md
+++ b/docs/development/setup-vagrant.md
@@ -156,7 +156,7 @@ Debian](https://docs.docker.com/install/linux/docker-ce/debian/).
 
 ```eval_rst
 .. note::
-    We now recommend using `WSL 2 for Windows development <../development/setup-advanced.html#installing-directly-on-windows-10-experimental>`_.
+    We recommend using `WSL 2 for Windows development <../development/setup-advanced.html#installing-directly-on-windows-10-with-wsl-2>`_.
 ```
 
 1. Install [Git for Windows][git-bash], which installs *Git BASH*.