chore: refactor after code review

README.md

@@ -7,62 +7,53 @@
 
 _Take control of your internal daemons!_
 
-**Pebble** is a lightweight Linux service manager that helps you orchestrate a set of local service processes as an organized set. It resembles well known tools such as _supervisord_, _runit_, or _s6_, in that it can easily manage non-system processes independently from the system services, but it was designed with unique features that help with more specific use cases.
+**Pebble** is a lightweight Linux service manager that helps you orchestrate a set of local processes as an organised set. It resembles well-known tools such as _supervisord_, _runit_, or _s6_, in that it can easily manage non-system processes independently from the system services. However, it was designed with unique features such as layered configuration and an HTTP API that help with more specific use cases.
 
 Pebble's key features:
 
-- Service management with [layers](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/layers/)
+- [Layer](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/layers/)-based configuration
 - Service [dependencies](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/service-dependencies/)
 - Service [logs](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/cli-commands/logs/) and [log forwarding](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/log-forwarding/)
 - [Health checks](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/health-checks/)
-- [Notices](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/notices/)
+- [Notices](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/notices/) (aggregated events)
 - Identities
-- Can be used in Machines and containers
-- [CLI](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/cli-commands/cli-commands/), [HTTP API and Go client](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/api-and-clients/)
+- Can be used in machines and [containers](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/pebble-in-containers/)
+- [CLI commands](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/cli-commands/cli-commands/)
+- [HTTP API](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/api-and-clients/) with a [Go client](https://pkg.go.dev/github.com/canonical/pebble/client) and a [Python client](https://github.com/canonical/operator/blob/main/ops/pebble.py)
 
 ## Quick start
 
 Prerequisites:
 
 - A Linux machine.
-- Python 3.x (used to run a basic HTTP server as a sample service managed by Pebble).
 
 ```bash
-git clone https://github.com/canonical/pebble.git
-cd pebble
-mkdir -p ~/PEBBLE/layers
-export PEBBLE=$HOME/PEBBLE
+go install github.com/canonical/pebble/cmd/pebble@latest
+mkdir -p ~/pebble_home/layers
+export PEBBLE=$HOME/pebble_home
+
 echo """\
-summary: Simple layer
-description: |
-    A simple layer.
 services:
-    http-server:
+    demo-service:
         override: replace
-        summary: demo http server
-        command: python3 -m http.server 8080
+        command: sleep 1000
         startup: enabled
-""" > $PEBBLE/layers/001-http-server.yaml
-go run ./cmd/pebble run
+""" > $PEBBLE/layers/001-demo-service.yaml
+
+pebble run
 ```
 
-You can also follow the [Getting started with Pebble tutorial](https://canonical-pebble.readthedocs-hosted.com/en/latest/tutorial/getting-started/).
+Read more about Pebble's general model [here](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/general-model/).
+
+For a slightly longer introduction, you can also go through the [official tutorial](https://canonical-pebble.readthedocs-hosted.com/en/latest/tutorial/getting-started/)
 
 ## Getting help
 
 If you need support, start with the [documentation](https://canonical-pebble.readthedocs-hosted.com/en/latest/).
 
-To learn more about Pebble, read the following sections:
+You can also [create an issue](https://github.com/canonical/pebble/issues/new) and we will help!
 
-- [General model](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/general-model/)
-- [Layer configuration examples](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/layers/)
-- [Container usage](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/pebble-in-containers/)
-- [Layer specification](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/layer-specification/)
-- [API and clients](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/api-and-clients/)
-- [Hacking / Development](#hacking--development)
-- [Contributing](#contributing)
-
-## Hacking / development
+## Hacking and development
 
 See [HACKING.md](HACKING.md) for information on how to run and hack on the Pebble codebase during development. In short, use `go run ./cmd/pebble`.
 
@@ -71,7 +62,3 @@ See [HACKING.md](HACKING.md) for information on how to run and hack on the Pebbl
 We welcome quality external contributions. We have good unit tests for much of the code, and a thorough code review process. Please note that unless it's a trivial fix, it's generally worth opening an issue to discuss before submitting a pull request.
 
 Before you contribute a pull request you should sign the [Canonical contributor agreement](https://ubuntu.com/legal/contributors) -- it's the easiest way for you to give us permission to use your contributions.
-
-## Have fun!
-
-... and enjoy the rest of the year!

docs/tutorial/getting-started.md

@@ -32,9 +32,9 @@ Now that Pebble has been installed, we can set up a basic configuration.
 First, let's create a directory for Pebble configuration and add the `PEBBLE` environment variable to `~/.bashrc`. 
 
 ```bash
-mkdir -p ~/PEBBLE/layers
-export PEBBLE=$HOME/PEBBLE
-echo "export PEBBLE=$HOME/PEBBLE" >> ~/.bashrc
+mkdir -p ~/.config/pebble/layers
+export PEBBLE=$HOME/.config/pebble
+echo "export PEBBLE=$HOME/.config/pebble" >> ~/.bashrc
 ```
 
 Next, create a [configuration layer](../reference/layers.md) by running: