Review compositor tutorial (#3606)

Another docs review. I've provided a bit more context to the code
creation part (at least as well as I myself could understand it).
Do you think the build definition of Cmake requires more explanations?
Or will it be a self-evident thing for a regular C++ developer?

Jira: https://warthogs.atlassian.net/browse/DOCPR-852

CMakeLists.txt

@@ -315,6 +315,6 @@ mir_check_no_unreleased_symbols(mirserver release-checks)
 
 if (TARGET doc)
   add_custom_target(doc-show
-          xdg-open ${CMAKE_BINARY_DIR}/doc/html/index.html
+          xdg-open ${CMAKE_BINARY_DIR}/doc/sphinx/_build/index.html
           DEPENDS doc)
 endif()

doc/sphinx/tutorial/write-your-first-wayland-compositor.md

@@ -2,47 +2,42 @@
 discourse: 4911,5164,5603,6756,8037
 ---
 
-# Write Your First Wayland Compositor
-This tutorial will guide you through writing a simple compositor: the
-installation of dependencies, building it, and running it. You'll be impressed
-by how easy it is to create a Wayland compositor using Mir!
+# Write your first Wayland compositor
+This tutorial will guide you through writing a basic Mir compositor. By the end of it, you will create, build, and run a program with basic window management
+capabilities such as controlling multiple windows, minimizing and maximizing, and handling mouse input. 
+
 
 ## Assumptions
+
 This tutorial assumes that:
-1. The reader is familiar with C++ and CMake.
-2. The reader has cmake and a C++ compiler installed
 
-## A barebones Mir compositor
-This section will cover the needed dependencies and how to install them, the
-minimum code needed for a Mir compositor, how to build this code, and finally
-how to run your compositor.
+* You are familiar with C++ and CMake.
+* You have `cmake` and a C++ compiler installed.
 
-### Dependencies
-Before you start coding, you'll need to install `libmiral`, and
-`mir-graphics-drivers-desktop` which can be done on different distros as
-follows:
+## Installing dependencies
+This section will cover the needed dependencies and how to install them.
+The example program requires 
+* `libmiral` - short for "Mir Abstraction Layer". Provides a high level interface to interact with and customize Mir compositors.
+* `mir-graphics-drivers-desktop` - provides drivers so Mir can talk with different graphics drivers
 
-Installing dependencies on Debian and its derivatives:
+### Install dependencies on Debian or derivatives:
 ```sh
 sudo apt install libmiral-dev mir-graphics-drivers-desktop
 ```
 
-<details>
-<summary> Installing Dependencies on Other Distros </summary>
-
-Installing dependencies on Fedora
+### Install dependencies on Fedora:
 ```sh
 sudo dnf install mir-devel libxkbcommon
 ```
-Installing dependencies on Alpine
+### Install dependencies on Alpine:
 ```sh
 sudo apk add mir-dev
 ```
-</details>
 
+## Coding a Mir compositor
+
+The following code defines a barebones Mir compositor:
 
-### Code
-The following code block is the bare minimum you need to run a Mir compositor:
 ```cpp
 #include <miral/runner.h>
 #include <miral/minimal_window_manager.h>
@@ -61,13 +56,17 @@ int main(int argc, char const* argv[])
 }
 ```
 
-This program creates a floating window manager with basic window management
-capabilities such as controlling multiple windows, minimizing and maximizing,
-and handling mouse input. This is done with the help of MirAL (Mir Abstraction
-Layer) which gives you a high level interface to work with Mir.
 
-### Building
-To compile this simple program, you can use this `CMakeLists.txt` file:
+`MirRunner` is a class from `libmiral` that acts as the "entry point" of your compositor.
+
+`MirRunner runner` creates a `runner` object that can be used to configure your compositor.  To run the compositor you call `runner.run_with(...)`, passing in different components to customize the behavior of the compositor. In this example, `run_with()` is passed a function `set_window_management_policy` that applies a `MinimalWindowManager` policy to the compositor. The compositor is therefore created with basic window management capabilities such as controlling multiple windows, minimizing and maximizing, and handling mouse input. 
+
+The runner allows for even more customization: enabling onscreen keyboards, screen capture, pointer confinement, and so on. 
+
+## Building a Mir compositor
+
+To compile this simple program, create a `CMakeLists.txt` file with the following content:
+
 ```cmake
 cmake_minimum_required(VERSION 3.5)
 
@@ -86,30 +85,29 @@ target_link_libraries(     demo-mir-compositor               ${MIRAL_LDFLAGS})
 target_link_libraries(     demo-mir-compositor               ${XKBCOMMON_LIBRARIES})
 ```
 
-Then to build:
+Then build it:
 ```sh
 cmake -B build
 cmake --build build
 ```
 
-### Running
-To run, you can run nested in an X or Wayland session, or from a virtual
-terminal, just like the demo applications in [Learn What Mir Can
-Do](learn-what-mir-can-do.md). For example, if we were to run inside an
-existing Wayland session, we'd run the following command:
+## Running a Mir compositor
+You can run a compositor nested in an X or Wayland session, or from a virtual terminal, just like the demo applications in [Getting started with Mir](getting-started-with-mir.md). 
+
+For example, to run inside an existing Wayland session:
 ```sh
 WAYLAND_DISPLAY=wayland-99 ./build/demo-mir-compositor
 ```
-You'll see a window housing the compositor with a black void filling it. To
-fill this void with some content, you can run the following from another
-terminal:
+An all-black window with the compositor will pop up.
+
+To change the black background of the window and display some content instead, open another terminal and run:
 ```sh
 WAYLAND_DISPLAY=wayland-99 bomber
 ```
-You're free to replace `bomber` with any other Wayland compatible application.
+Try moving it around the screen, maximizing and restoring it. This functionality is provided by the `MinimalWindowManager` policy that you have added to your compositor. You can replace `bomber` with any other Wayland-compatible application.
 
 ## Next steps
-Now that you have your base compositor working, feel free to check out these guides on how to further develop your compositor:
+Now that you have your base compositor working, check out these guides on how to further develop your compositor:
 
 - [How to specify start up applications](/how-to/how-to-specify-startup-apps.md)
 - [How to handle user input](/how-to/how-to-handle-keyboard-input.md)