From 8d789a9d9f17a03feff7b4fbeb1d2d304315279c Mon Sep 17 00:00:00 2001
From: Andrew Farries <andrew.farries@xata.io>
Date: Wed, 27 Sep 2023 07:06:41 +0100
Subject: [PATCH] Add tutorial section to `docs/README.md`

---
 docs/README.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/README.md b/docs/README.md
index eb8b4049e..6bb9adddd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,7 +12,44 @@
 
 ## Installation
 
-## Getting started
+## Tutorial
+
+This section will walk you through applying your first migrations using `pgroll`.
+
+Prerequisites:
+
+* `pgroll` installed and accessible somewhere on your `$PATH`
+* A fresh Postgres instance against which to run migrations.
+
+A good way to get a throw-away Postgres instance for use in the tutorial is to use [Docker](https://www.docker.com/). Start a Postgres instance in Docker with:
+
+```
+docker run --rm --name for-pgroll -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
+```
+
+The remainder of the tutorial assumes that you have a local Postgres instance accessible on port 5432.
+
+### Initialization
+
+`pgroll` needs to store its own internal state somewhere in the target Postgres instance. Initializing `pgroll` configures this store and makes `pgroll` ready for first use:
+
+```
+pgroll init
+```
+
+You should see a success message indicating that `pgroll` has been configured.
+
+<details>
+  <summary>**What data does pgroll store**?</summary>
+  
+  ## Heading
+  1. A numbered list item
+  2. Another numbered list item
+  
+  ```go
+  fmt.Println("Hello, world!")
+  ```
+</details>
 
 ## Command line reference