chore: refactor tutorial according to anne PR

docs/explanation/index.md

@@ -1,7 +1,6 @@
 # Explanation
 
 ```{toctree}
-:hidden:
 :titlesonly:
 :maxdepth: 1
 

docs/how-to/index.md

@@ -1,7 +1,6 @@
 # How-to guides
 
 ```{toctree}
-:hidden:
 :titlesonly:
 :maxdepth: 1
 

docs/tutorial/getting-started.md

@@ -1,14 +1,15 @@
 # Getting started
 
-In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services. It takes about 15 minutes to complete. After this tutorial, you will have a basic understanding of what Pebble is, how to install it, and how to use it to orchestrate services. After that, you can continue exploring more advanced features and use cases (see links at the end).
+In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services. After this tutorial, you will have a basic understanding of what Pebble is, how to install it, and how to use it to orchestrate services. It takes about 15 minutes to complete.
+
+
+After that, you can continue exploring more advanced features and use cases (links at the end).
 
 ## Prerequisites
 
 - A Linux machine.
 
-## Install Pebble
-
-### Download and install the latest release
+## Download and install Pebble
 
 Find the latest tag on the [latest release page](https://github.com/canonical/pebble/releases/latest), then run the following commands to download, extract, and install the latest release (replace `v1.11.0` with the latest tag and `amd64` with your architecture):
 
@@ -18,17 +19,15 @@ tar zxvf pebble_v1.11.0_linux_amd64.tar.gz
 sudo mv pebble /usr/local/bin/ # make sure it's in your $PATH
 ```
 
-### Install from source
+## Verify Pebble installation
 
-Alternatively, you can build and install Pebble from source:
+Once the installation is complete, verify that `pebble` has been installed correctly by running:
 
-1. Follow the official Go documentation [here](https://go.dev/doc/install) to download and install Go.
-2. After installing, you will want to add the `$GOBIN` directory to your `$PATH` so you can use the installed tools. For more information, refer to the [official documentation](https://go.dev/doc/install/source#environment).
-3. Run `go install github.com/canonical/pebble/cmd/pebble@latest` to build and install Pebble.
-
-### Check that it's working
+```bash
+pebble
+```
 
-After installation, if you run `pebble`, you should see some output equivalent to the following:
+This should produce output similar to the following:
 
 ```bash
 Pebble lets you control services and perform management actions on
@@ -41,15 +40,17 @@ Usage: pebble <command> [<options>...]
 
 ## Configure Pebble
 
-First, create a directory for Pebble configuration:
+Now that Pebble has been installed, we can set up a basic configuration.
+
+First, let's create a directory for Pebble configuration:
 
 ```bash
 mkdir -p ~/PEBBLE/layers
 export PEBBLE=$HOME/PEBBLE
 echo "export PEBBLE=$HOME/PEBBLE" >> ~/.bashrc # add $PEBBLE to your bashrc
 ```
 
-Then, create a simple layer:
+Next, create a layer by running:
 
 ```bash
 echo """\
@@ -69,15 +70,19 @@ services:
 
 This creates a simple layer containing only one service (which runs a basic HTTP server using Python's `http` module, listening on port 8080).
 
-## Run the Pebble daemon
+## Start the Pebble daemon
+
+Now we are ready to run the Pebble daemon.
 
 Pebble is invoked using `pebble <command>`. (To get more information, run `pebble -h`.)
 
+To start the daemon, run:
+
 ```bash
 pebble run
 ```
 
-You should get some output similar to the following:
+This starts the Pebble daemon itself, as well as all the services that are marked as `startup: enabled` (in our simple layer created above, the `http-server` service is marked as `startup: enabled`). You should get some output similar to the following:
 
 ```bash
 2024-06-02T11:30:02.925Z [pebble] Started daemon.
@@ -87,51 +92,49 @@ You should get some output similar to the following:
 ...
 ```
 
-This starts the Pebble daemon, and as you can see from the log, our HTTP server is already started, which can be verified by running `curl localhost:8080` in another terminal tab.
+As you can see from the log, our HTTP server is started too, which can be verified by running `curl localhost:8080` in another terminal tab.
 
-To exit the Pebble daemon, press Ctrl-C (which sends an "interrupt" signal to the process).
+> Note: To exit the Pebble daemon, press Ctrl-C (which sends an "interrupt" signal to the process).
 
-## View, start, and stop services
+## View, start and stop services
 
-You can view the status of services by running `pebble services`. Open another terminal tab, and run:
+While the Pebble daemon is running, you can view the status of services by running `pebble services`. Open another terminal tab, and run:
 
 ```bash
 pebble services
 ```
 
-You should see output similar to:
+You should see output similar to the following:
 
 ```bash
 Service      Startup  Current  Since
 http-server  enabled  active   today at 11:30 UTC
 ```
 
-Use `pebble stop <service1> <service2> ...` to stop one or more services. Run:
+Use `pebble stop <service1> <service2> ...` to stop one or more services. You can stop the running `http-server` service by running:
 
 ```bash
 pebble stop http-server
 ```
 
-And the service `http-server` is stopped. We can verify it by viewing all the services: Run `pebble services`, and you can see it from the output:
+You should get output similar to the following:
 
 ```bash
 Service      Startup  Current   Since
 http-server  enabled  inactive  today at 11:33 UTC
 ```
 
-And, if we run `curl localhost:8080`, we get a "connection refused" error, which confirms the service is down.
+Now the service `http-server` is stopped. If we run `curl localhost:8080` again, we get a "connection refused" error, which confirms the service is down.
 
 To start it again, run:
 
 ```bash
 pebble start http-server
 ```
 
-And it's started now.
-
 ## Add a new layer
 
-Now let's add another layer containing a different HTTP server. Create a new layer:
+Now let's add another layer containing a different service that is also an HTTP server. To create a new layer, run:
 
 ```bash
 echo """\
@@ -146,28 +149,30 @@ services:
         summary: demo http server 2
         command: python3 -m http.server 8081
         startup: enabled
-""" > $PEBBLE/layers/002-another-server.yaml
+""" > $PEBBLE/layers/002-another-http-server.yaml
 ```
 
-This creates another layer containing only one service running an HTTP server listening on a different port 8081. Then let's add this layer to a plan:
+This creates another layer that also contains a single service (running a basic
+HTTP server using the Python `http.server` module listening on a different port 8081).
+
+Add the new layer to a Pebble plan by running:
 
 ```bash
-pebble add layer1 $PEBBLE/layers/002-another-server.yaml
+pebble add layer1 $PEBBLE/layers/002-another-http-server.yaml
 ```
 
-You will see output similar to the following:
+If the layer is added successfully, the above command should produce the following output:
 
 ```bash
-Layer "layer1" added successfully from "/home/ubuntu/PEBBLE_HOME/layers/002-another-server.yaml"
+Layer "layer1" added successfully from "/home/ubuntu/PEBBLE_HOME/layers/002-another-http-server.yaml"
 ```
 
-When we update the service configuration by adding a layer, the services changed won't be automatically restarted. If we check the services:
+Even though the service configuration has been updated with the newly added layer, the newly added services won't be automatically started. If we check the services:
 
 ```bash
 pebble services
 ```
-
-We can see that although a new service has been added, it's not active yet:
+We can see that although the new service `http-server-2` has been added, it's still "inactive":
 
 ```bash
 Service        Startup  Current   Since
@@ -187,21 +192,21 @@ And you get output similar to:
 2024-06-02T11:40:39Z INFO Service "http-server" already started.
 ```
 
-Now if we check all the services:
+Now if we check all the services again:
 
 ```bash
 pebble services
 ```
 
-We can see that the new HTTP server defined in the newly added layer has been started as well:
+We can see that the new HTTP server `http-server-2` defined in the newly added layer should have been started and be shown as "active":
 
 ```bash
 Service        Startup  Current  Since
 http-server    enabled  active   today at 11:34 UTC
 http-server-2  enabled  active   today at 11:40 UTC
 ```
 
-## Where to go from here
+## Next steps
 
 - To learn more about running the Pebble daemon, see [How to run the daemon (server)](../how-to/run-the-daemon.md).
 - To learn more about viewing, starting and stopping services, see [How to view, start, and stop services](../how-to/view-start-stop-services.md).