What we’re reworking
A README section on restoring the database — one paragraph, the way it’s usually written from memory:
Restore
In order to restore the database from a backup, you first need to stop WordPress, otherwise it will write to the database during the restore and the data will get mixed up. Backups are kept in the /srv/backup/mariadb directory, they’re created every night at 3:00 and kept for 14 days, and the files are named by date. To restore, unpack the file you need and pass it to mariadb inside the container; the password comes from an environment variable. After that, start WordPress and check that the site opens and the latest posts are there. If the restore fails with an Access denied error, the root password in .env was changed after the database was created.
## Restore
In order to restore the database from a backup, you first need to stop WordPress, otherwise it
will write to the database during the restore and the data will get mixed up. Backups are kept
in the /srv/backup/mariadb directory, they're created every night at 3:00 and kept for 14 days,
and the files are named by date. To restore, unpack the file you need and pass it to mariadb
inside the container; the password comes from an environment variable. After that, start
WordPress and check that the site opens and the latest posts are there. If the restore fails
with an Access denied error, the root password in .env was changed after the database was created.Everything you need is here. You just can’t find it: the backup path is in the middle of the third line, there’s no command at all, and the warning about WordPress is dissolved in the first sentence.
Reworking it
Write down the questions people bring to the text
Nobody comes here to read about backups; they come with one of these questions:
- Where are the backups, and for which days?
- How do I restore?
- How do I know it worked?
- It won’t restore — what now?
Each question is a future section or block. A question the paragraph never asks shows up already at this point: “how do I restore a single table”, for example — either add it or leave it out on purpose.
The main answer — in the first sentence
The section’s first sentence answers the main question, with no “in order to”:
README.md Database backups are in
/srv/backup/mariadb, one per night, for the last 14 days. Restore with WordPress stopped.Database backups are in `/srv/backup/mariadb`, one per night, for the last 14 days. Restore with WordPress stopped.After two lines it’s clear whether the backup you need exists and what to do first. The rest is detail (Answer first).
Cut by question; a heading is the section’s point
One question, one subheading. The heading holds an answer or an action, not a topic:
Before After Restore Restore in 4 steps Notes If the backup won’t restore — Where the backups live The check: the headings read in a row are the page’s plan (Headings say what’s inside).
Actions in order — a numbered list, commands — a code block
A step is one action and what should happen. A command goes in a code block so it gets copied whole instead of retyped from the middle of a sentence:
README.md -
Stop WordPress; the database keeps running:
docker compose stop wordpress -
Load the backup for the date you need:
gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \ | docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'The command prints nothing — that’s normal. An error shows up as text right away.
1. Stop WordPress; the database keeps running: ```bash docker compose stop wordpress ``` 2. Load the backup for the date you need: ```bash gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \ | docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"' ``` The command prints nothing — that's normal. An error shows up as text right away.Without numbering, order gets lost when scanning: “first stop” in a paragraph reads as advice, not as step one.
-
Uniform facts — a list or a table
The path, the time, the retention and the file name are four facts of one kind. In the paragraph they’re separated by commas; in a table they read at a glance:
README.md What Value Where /srv/backup/mariadbWhen every night at 3:00 Kept for 14 days File name the backup’s date: 2026-10-18.sql.gz| What | Value | |---|---| | Where | `/srv/backup/mariadb` | | When | every night at 3:00 | | Kept for | 14 days | | File name | the backup's date: `2026-10-18.sql.gz` |The key word — at the start of the line
The eye takes the first two words of a list item, about 11 characters (Key word first). The item “If the restore fails with an Access denied error” starts with the filler “if the”; starting with “
Access denied— the root password was changed after the database was created” says at once what the line is about.Highlight one place
There’s one warning: WordPress writes to the database during the restore. It’s already in the first sentence and the first step — a third highlight (bold, a panel, caps) isn’t needed. When one place is highlighted, you see it; when five are, you see none (Bold: one or two spots).
Read only the headings and the first words
Cover the text with your hand, leaving only the headings and the first words of lines, and quiz yourself with the questions from the first step. If every question shows an answer or the place where it lives, the text is scannable. If not, go back to step 3. The other checks before publishing — Checking presentation.
What came out
Restoring the database from a backup
Database backups are in /srv/backup/mariadb, one per night, for the last 14 days.
Restore with WordPress stopped: otherwise it writes to the database mid-restore.
Where the backups live
| What | Value |
|---|---|
| Where | /srv/backup/mariadb |
| When | every night at 3:00 |
| Kept for | 14 days |
| File name | the backup’s date: 2026-10-18.sql.gz |
Restore in 4 steps
-
Stop WordPress; the database keeps running:
docker compose stop wordpress. -
Load the backup for the date you need:
gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \ | docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'The command prints nothing — that’s normal.
-
Start WordPress:
docker compose start wordpress. -
Open the site and check that the latest post is from the backup’s date.
If the backup won’t restore
Access denied for user 'root'— the root password in.envwas changed after the database was created. The database remembers the old one: write it in, or change the password inside the database.No such file or directory— there’s no backup for that date:ls /srv/backup/mariadb.
## Restoring the database from a backup
Database backups are in `/srv/backup/mariadb`, one per night, for the last 14 days.
Restore with WordPress stopped: otherwise it writes to the database mid-restore.
### Where the backups live
| What | Value |
|---|---|
| Where | `/srv/backup/mariadb` |
| When | every night at 3:00 |
| Kept for | 14 days |
| File name | the backup's date: `2026-10-18.sql.gz` |
### Restore in 4 steps
1. Stop WordPress; the database keeps running: `docker compose stop wordpress`.
2. Load the backup for the date you need:
```bash
gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \
| docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'
```
The command prints nothing — that's normal.
3. Start WordPress: `docker compose start wordpress`.
4. Open the site and check that the latest post is from the backup's date.
### If the backup won't restore
- `Access denied for user 'root'` — the root password in `.env` was changed after the database
was created. The database remembers the old one: write it in, or change the password inside the database.
- `No such file or directory` — there's no backup for that date: `ls /srv/backup/mariadb`.The text grew by about 40%, 169 words against 120 outside the code blocks: commands, a table and a second error were added. In return, the backup path is visible in the second line, the command gets copied whole, and the error is found by searching for its text.
How to check
- Read only the headings in a row. If you get the page’s plan, good; if you get “Description, Setup, Other”, rewrite the headings.
- Give the text to someone with one of the questions and watch how they search. If they run down the headings and point at the answer, good; if they start reading from the first line, the answer is hidden.
- Search the page with
Ctrl+Ffor the error text from “If it doesn’t work” — the line with the error should start with it.
If it doesn’t work
There are headings, but people still read straight through to find things
- Cause
- The headings name a topic (“Restore”) rather than answer: they don’t show what’s inside or where the answer is.
- Fix
- Put the section’s point in the heading: “Restore in 4 steps”, “If the backup won’t restore” (Headings say what’s inside).
An eight-item list reads worse than the paragraph did
- Cause
- Steps, facts and warnings are mixed in one list — the items are different in kind, and the eye can’t tell what it’s looking at.
- Fix
- Steps as a numbered list, facts as a table or a list of their own, the warning separately (Chunking text).
After the rework the text got twice as long
- Cause
- Every item gained an introduction and a restatement of its heading.
- Fix
- A section’s first sentence answers rather than repeats the heading; strike connectors like “next”, “also”.