more maintainer glory

docs/maintainers/tutorial.md

@@ -4,16 +4,26 @@ title: New maintainers tutorial
 
 ## Package your first recipe
 
-Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them all, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.
+### Overview
 
-Let's take as an example, [Matomo web analytics](https://matomo.org/). We'll be making a Docker "swarm-mode" `compose.yml` file. Here's an overview of the options you'd have to package Matomo:
+Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.
+
+The nice thing about packaging is that only one person has to do it and then we all benefit. We've seen that over time, the core of the configuration doesn't really change. New options and versions might come but the config remains quite stable. This is good since it meand that your packaging work stays relevant and useful for other maintainers & operators as time goes on.
+
+### Making a plan
+
+The idea scenario is when the upstream project provides both the packaged image and a compose configuration which we can build from. If you're in luck, you'll typically find a `Dockerfile` and a `docker-compose.yml` file in the root of the upstream Git repository for the app.
 
 - **Tired**: Write your own image and compose file from scratch
 - **Wired**: Use someone else's image (& maybe compose file)
 - **Inspired**: Upstream image, someone else's compose file
-- **On fire**: Upstream image, Upstream compose file
+- **On fire**: Upstream image, upstream compose file
 
-Luckily, Matomo already has an example compose file in their repository. Like a lot of compose files, it's intended for use with `docker-compose`, instead of "swarm mode", but it should be a good start. That typically also means "not for production" but we can still use it as a solid base.
+### Writing the `compose.yml`
+
+Let's take a practical example, [Matomo web analytics](https://matomo.org/). We'll be making a Docker "swarm-mode" `compose.yml` file.
+
+Luckily, Matomo already has an example compose file in their repository. Like a lot of compose files, it's intended for use with `docker-compose`, instead of "swarm mode", but it should be a good start.
 
 First, let's create a directory with the files we need:
 
@@ -40,6 +50,8 @@ Open the `compose.yml` in your favourite editor and have a gander 🦢. The
 
 The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
 
+### Test deployment
+
 !!! note "Running Co-op Cloud server required!"
 
     The rest of this guide assumes you have a Co-op Cloud server going -- we'll use `swarm.example.com`, but replace it with your own server address. Head over to [the operators tutorial](/operators/tutorial) if you need help setting one up.
@@ -64,4 +76,6 @@ abra app deploy swarm.example.com
 
 Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
 
-Congrats, you've packaged your first recipe! You've probably got more questions, check out the [maintainers handbook](/maintainers/handbook)!
+### Finishing up
+
+You've probably got more questions, check out the [maintainers handbook](/maintainers/handbook)!