docs: improvements based on feedback from anne and daniele (#459)

Minor docs improvements.
canonical · Aug 1, 2024 · 59cada8 · 59cada8
1 parent 2aca1ff
commit 59cada8
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 4 deletions.
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -1,9 +1,25 @@
 # How-to guides
 
+These guides will walk you through every step of using Pebble through its complete operations lifecycle.
+
+## Installation
+
+Installation follows a broadly similar pattern on all architectures, and you can choose to install the pre-built binary or build it from the source by yourself.
+
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
 
 Install Pebble <install-pebble>
+```
+
+## Service Orchestration
+
+As your needs grow, you may want to orchestrate multiple services.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
 Manage service dependencies <service-dependencies>
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -40,7 +40,6 @@ The Pebble project is sponsored by [Canonical Ltd](https://www.canonical.com).
 :hidden:
 :titlesonly:
 
-:diataxis:self
 :diataxis:Tutorial <tutorial/getting-started>
 :diataxis:how-to/index
 :diataxis:explanation/index

diff --git a/docs/reference/layers.md b/docs/reference/layers.md
@@ -1,6 +1,6 @@
 # Layers
 
-The `$PEBBLE` directory must contain a `layers/` subdirectory that holds a stack of configuration files with names similar to `001-base-layer.yaml`, where the digits define the order of the layer and the following label uniquely identifies it.
+The `$PEBBLE` directory must contain a `layers/` subdirectory, representing Pebble configuration split over a stack of configuration files ("layers") with names similar to `001-base-layer.yaml`, where the digits define the order of the layer and the following label uniquely identifies it. Pebble includes layers in alphabetical order so that the last ones can modify a configuration element defined in one of the first ones.
 
 ## Examples
 

diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md
@@ -1,6 +1,6 @@
 # Getting started with Pebble
 
-In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services. This tutorial takes about 15 minutes to complete.
+In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services to discover some of Pebble's basic service orchestration capabilities. At the end of the tutorial, we should have two running HTTP servers listening on different ports managed by Pebble. This tutorial takes about 15 minutes to complete.
 
 After this tutorial, you will have a basic understanding of what Pebble is and how to use it to orchestrate services, and you can continue exploring more advanced features and use cases (see {ref}`next_steps`).
 
@@ -36,7 +36,7 @@ export PEBBLE=$HOME/PEBBLE
 echo "export PEBBLE=$HOME/PEBBLE" >> ~/.bashrc
 ```
 
-Next, create a layer by running:
+Next, create a [configuration layer](../reference/layers.md) by running:
 
 ```{code-block} bash
 :emphasize-lines: 8