Closes https://github.com/canonical/ubuntu-pro-for-wsl/issues/1357

[HenderRicard]

Closes canonical/ubuntu-pro-for-wsl#1357

Issues

Our tutorials and guides, and those of others, have generally assumed a specific behavior when a user runs the wsl --install command.

We have been trying to account better for how this command, has a different effect depending on whether WSL is already installed, whether Virtual Machine Platform is enabled, whether a reboot has been performed, and so on.

As we don't have control over this behaviour, we need to document it in a way that guides the user in such a way as to minimize variation; where this is not possible, we should explain the variation.

Another potential source of unpredictability is whether virtualisation is enabled on a user machine, or whether they are following instructions while using WSL in a VM.

The changes outlined below apply primarily to the Develop with Ubuntu on WSL tutorial, and are aimed at providing further clarity to users. Similar updates are also applied to the installation how-to guide and the getting started with UP4W guide, where appropriate.

Approach

Ask the user to check their WSL installation

The develop with Ubuntu on WSL tutorial now asks the user to check is WSL is installed.

They are then directed to an "install WSL" or "install Ubuntu" section depending on the outcome.

This helps reduce the need for us to invoke wsl --install for two different purposes (enabling WSL, installing Ubuntu) and explain the difference.

Note

I considered recommending wsl --install --no-distribution.
This would ensure further consistency, as it would separate WSL setup from Ubuntu installation.
However, it might make the command seem more complex to a new user, so I opted against it for now.

Add a virtualisation section to requirements

Most users probably have virtualisation enabled, most users probably aren't running WSL in a VM, and most users probably aren't concerned about the Virtual Machine Platform. For those who are affected, however, it could cause problems and the solution might be unclear.

We provide this information as an optional dropdown, with supporting links to the MS documentation:

This is also an appropriate place to mention Virtual Machine Platform, which is responsible for some of the variation in behaviour reported by users.

Add a note on the --name flag

A user may want to follow the develop with Ubuntu on WSL tutorial without removing or backing up an existing instance of Ubuntu 24.04.

In most cases, it's probably more convenient to just install a fresh instance with a different name.

This also gives us an opportunity to demonstrate a lesser known functionality.

Note on the use of dropdowns

The documentation tooling comes with the Sphinx Design extension built-in.

When we have used dropdowns in the past, we have used Sphinx Design; however, the default dropdown styling is not very good:

The dropdowns have optional parameters for icons and theming, which makes it easier to differentiate them.

This PR uses dropdowns in a specific way:

• For optional content that most users will likely not need
• Always closed by default
• Using a single, functional colorscheme (black and white)

In this way, they do not fully replace our standard use of admonitions.

Note on includes

I cleaned up our includes so that they are now in their own directory.

I have also added additional includes for content that will be reused in multiple places:

• Explanation of prompts
• Virtualisation requirements

Note on tutorials and how-tos

In Diataxis, we generally try to avoid providing optional routes in tutorials.

A tutorial is supposed to be an end-to-end learning experience with a single path to success.

It is appropriate to instruct users to install and use Ubuntu-24.04 in the tutorial after first checking their WSL installation, which obviates the need to explain variations in installation behaviour.

The use of dropdowns may still be needed to provide escape hatches for people who have diverged from the instructions. For example, someone who finds that they already have 24.04 installed and don't want to deal with backups.

The use of dropdowns is also appropriate for optional information, like virtualisation requirements, which could otherwise distract or confuse users who don't need to think about those details. That optional information does not affect the path that we are suggesting in the tutorial.

UDENG-8053

Publicación original de @edibotopic en canonical/ubuntu-pro-for-wsl#1399