docs: add explanations for how to manage service dependencies

docs/explanation/index.md

@@ -4,6 +4,8 @@
 :titlesonly:
 :maxdepth: 1
 
-General model <general-model>
 API and clients <api-and-clients>
+General model <general-model>
+Service dependencies <service-dependencies>
+Service start order <service-start-order>
 ```

docs/explanation/service-dependencies.md

@@ -0,0 +1,11 @@
+# Service dependencies
+
+Pebble can take service dependencies into account when managing services: this is done with the `requires` list in the [service definition](../reference/layer-specification.md).
+
+Simply put, you can configure a list of other services in the `requires` section to indicate this service requires those other services to start correctly.
+
+When Pebble starts a service, it also starts the services which that service depends on (configured with `requires`). Conversely, when stopping a service, Pebble also stops services which depend on that service.
+
+For the start order of the services, see [Service start order](./service-start-order.md).
+
+For example, if service `nginx` requires `logger`, `pebble start nginx` will start both `nginx` and `logger` (in an undefined order). Running `pebble stop logger` will stop both `nginx` and `logger`; however, running `pebble stop nginx` will only stop `nginx` (`nginx` depends on `logger`, not the other way around).

docs/explanation/service-start-order.md

@@ -0,0 +1,10 @@
+# Service start order
+
+When multiple services need to be started together, they're started in order according to the `before` and `after` in the [layer configuration](../reference/layer-specification.md). Pebble waits 1 second after starting each service to ensure the command doesn't exit too quickly.
+
+The `before` option is a list of services that this service must start before (it may or may not `requires` them, see [Service dependencies](./service-dependencies.md)). Or if it's easier to specify this ordering the other way around, `after` is a list of services that this service must start after.
+
+```{include} /reuse/service-start-order.md
+   :start-after: Start: Service start order note
+   :end-before: End: Service start order note
+```

docs/how-to/service-dependencies.md

@@ -153,6 +153,8 @@ In the layer configuration above, the `frontend` service is dependent on the
 `backend` service, and the `backend` service is dependent on the `database`
 service.
 
+For more information on `requires`, see [Service dependencies](../explanation/service-dependencies.md).
+
 ### Specify start order for dependent services
 
 To specify the order in which one or more dependent services must start
@@ -188,13 +190,12 @@ In the updated layer above, the `frontend` service requires the `backend`
 service to be started before it, and the `backend` service requires the
 `database` service to be started before it.
 
-```{note}
-Currently, `before` and `after` are of limited usefulness, because Pebble only waits 1 second before moving on to start the next service, with no additional checks that the previous service is operating correctly.
-
-If the configuration of `before` and `after` for the services results in a cycle, an error will be returned when the Pebble daemon starts (and the plan is loaded) or when a layer that causes a cycle is added.
+```{include} /reuse/service-start-order.md
+   :start-after: Start: Service start order note
+   :end-before: End: Service start order note
 ```
 
-% Does it only check that the status is "Active"? So what does `requires` do?
+For more information on `before` and `after`, see [Service start order](../explanation/service-start-order.md).
 
 ## Verify service dependencies
 

docs/reuse/service-start-order.md

@@ -0,0 +1,9 @@
+Start: Service start order note
+
+```{note}
+Currently, `before` and `after` are of limited usefulness, because Pebble only waits 1 second before moving on to start the next service, with no additional checks that the previous service is operating correctly.
+
+If the configuration of `before` and `after` for the services results in a cycle, an error will be returned when the Pebble daemon starts (and the plan is loaded) or when a layer that causes a cycle is added.
+```
+
+End: Service start order note