basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Сканируемый текст: переделываем стену абзацев по шагам

    Текст сканируемый, если его понимают по заголовкам и первым словам строк, не читая подряд. Переделываем по шагам настоящий абзац из README — восстановление базы из копии — и в конце проверяем, что получилось, чтением одних заголовков.

    Что переделываем

    Раздел README про восстановление базы — одним абзацем, как его обычно пишут по памяти:

    README.md

    Восстановление

    Для того чтобы восстановить базу из резервной копии, сначала нужно остановить WordPress, иначе он будет писать в базу во время восстановления и данные перемешаются. Резервные копии лежат в каталоге /srv/backup/mariadb, они создаются каждую ночь в 3:00 и хранятся 14 дней, файлы называются по дате. Для восстановления распаковываем нужный файл и передаём его в mariadb внутри контейнера, пароль берётся из переменной окружения. После этого запускаем WordPress и проверяем, что сайт открывается и последние записи на месте. Если восстановление падает с ошибкой Access denied, значит в .env поменяли пароль root после того, как база была создана.

    ## Восстановление
    
    Для того чтобы восстановить базу из резервной копии, сначала нужно остановить WordPress, иначе
    он будет писать в базу во время восстановления и данные перемешаются. Резервные копии лежат
    в каталоге /srv/backup/mariadb, они создаются каждую ночь в 3:00 и хранятся 14 дней, файлы
    называются по дате. Для восстановления распаковываем нужный файл и передаём его в mariadb внутри
    контейнера, пароль берётся из переменной окружения. После этого запускаем WordPress и проверяем,
    что сайт открывается и последние записи на месте. Если восстановление падает с ошибкой Access
    denied, значит в .env поменяли пароль root после того, как база была создана.

    Всё нужное здесь есть. Найти его нельзя: путь к копиям — в середине третьей строки, команды нет совсем, предупреждение про WordPress растворено в первом предложении.

    Переделываем

    1. Выписываем вопросы, с которыми приходят к тексту

      Сюда приходят не почитать про бэкапы, а с одним из вопросов:

      1. Где лежат копии и за какие дни они есть?
      2. Как восстановить?
      3. Как понять, что восстановилось?
      4. Не восстанавливается — что делать?

      Каждый вопрос — будущий раздел или блок. Вопрос, который в абзаце не задан, видно уже здесь: например, «как восстановить одну таблицу» — его либо добавляем, либо осознанно оставляем за бортом.

    2. Главный ответ — в первую фразу

      Первая фраза раздела отвечает на главный вопрос, без «для того чтобы»:

      README.md

      Копии базы — в /srv/backup/mariadb, по одной за ночь, за последние 14 дней. Восстанавливаем при остановленном WordPress.

      Копии базы — в `/srv/backup/mariadb`, по одной за ночь, за последние 14 дней.
      Восстанавливаем при остановленном WordPress.

      После двух строк понятно, есть ли нужная копия и что сделать первым. Остальное — подробности («Ответ первым»).

    3. Режем по вопросам, заголовок — суть раздела

      Один вопрос — один подзаголовок. В заголовке — ответ или действие, а не тема:

      Было Стало
      Восстановление Восстановление за 4 шага
      Примечания Если копия не восстанавливается
      — Где лежат копии

      Проверка: заголовки, прочитанные подряд, — это план страницы («Заголовок говорит, что внутри»).

    4. Действия по порядку — нумерованным списком, команды — блоком кода

      Шаг — одно действие и то, что должно получиться. Команда — блоком кода, чтобы её скопировали целиком, а не перепечатали из середины предложения:

      README.md
      1. Останавливаем WordPress, база остаётся работать:

        docker compose stop wordpress
      2. Заливаем копию за нужную дату:

        gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \
          | docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'

        Команда ничего не выводит — это нормально. Ошибка — сразу текстом.

      1. Останавливаем WordPress, база остаётся работать:
      
         ```bash
         docker compose stop wordpress
         ```
      
      2. Заливаем копию за нужную дату:
      
         ```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"'
         ```
      
         Команда ничего не выводит — это нормально. Ошибка — сразу текстом.

      Без нумерации порядок теряется при сканировании: «сначала остановить» в абзаце читается как совет, а не как первый шаг.

    5. Однородные факты — списком или таблицей

      Путь, время, срок хранения и имя файла — четыре факта одного рода. В абзаце они разделены запятыми, в таблице читаются с одного взгляда:

      README.md
      Что Значение
      Где /srv/backup/mariadb
      Когда каждую ночь в 3:00
      Сколько хранятся 14 дней
      Имя файла дата копии: 2026-10-18.sql.gz
      | Что | Значение |
      |---|---|
      | Где | `/srv/backup/mariadb` |
      | Когда | каждую ночь в 3:00 |
      | Сколько хранятся | 14 дней |
      | Имя файла | дата копии: `2026-10-18.sql.gz` |
    6. Главное слово — в начало строки

      Из пункта списка глаз берёт первые два слова, около 11 знаков («Главное слово — в начало»). Пункт «Если восстановление падает с ошибкой Access denied» начинается со служебного «если»; начало «Access denied — пароль root поменяли после создания базы» сразу говорит, про что строка.

    7. Выделяем одно место

      Предупреждение одно: WordPress пишет в базу во время восстановления. Оно уже стоит в первой фразе и в первом шаге — третьего выделения (жирного, плашки, капса) не нужно. Когда выделено одно место, его видно; когда пять — не видно ни одного («Жирный — одно-два места»).

    8. Читаем только заголовки и первые слова

      Закрываем текст ладонью до заголовков и первых слов строк и спрашиваем себя по вопросам из первого шага. На каждый вопрос виден ответ или место, где он лежит, — текст сканируемый. Не виден — возвращаемся к шагу 3. Остальные проверки перед публикацией — «Проверка подачи».

    Что получилось

    README.md

    Восстановление базы из копии

    Копии базы — в /srv/backup/mariadb, по одной за ночь, за последние 14 дней. Восстанавливаем при остановленном WordPress: иначе он пишет в базу прямо во время заливки.

    Где лежат копии

    Что Значение
    Где /srv/backup/mariadb
    Когда каждую ночь в 3:00
    Сколько хранятся 14 дней
    Имя файла дата копии: 2026-10-18.sql.gz

    Восстановление за 4 шага

    1. Останавливаем WordPress, база остаётся работать: docker compose stop wordpress.

    2. Заливаем копию за нужную дату:

      gunzip -c /srv/backup/mariadb/2026-10-18.sql.gz \
        | docker compose exec -T mariadb sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"'

      Команда ничего не выводит — это нормально.

    3. Запускаем WordPress: docker compose start wordpress.

    4. Открываем сайт и смотрим, что последняя запись — от даты копии.

    Если копия не восстанавливается

    • Access denied for user 'root' — пароль root в .env поменяли после создания базы. База помнит старый: вписываем его или меняем пароль внутри базы.
    • No such file or directory — копии за эту дату нет: ls /srv/backup/mariadb.
    ## Восстановление базы из копии
    
    Копии базы — в `/srv/backup/mariadb`, по одной за ночь, за последние 14 дней.
    Восстанавливаем при остановленном WordPress: иначе он пишет в базу прямо во время заливки.
    
    ### Где лежат копии
    
    | Что | Значение |
    |---|---|
    | Где | `/srv/backup/mariadb` |
    | Когда | каждую ночь в 3:00 |
    | Сколько хранятся | 14 дней |
    | Имя файла | дата копии: `2026-10-18.sql.gz` |
    
    ### Восстановление за 4 шага
    
    1. Останавливаем WordPress, база остаётся работать: `docker compose stop wordpress`.
    2. Заливаем копию за нужную дату:
    
       ```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"'
       ```
    
       Команда ничего не выводит — это нормально.
    3. Запускаем WordPress: `docker compose start wordpress`.
    4. Открываем сайт и смотрим, что последняя запись — от даты копии.
    
    ### Если копия не восстанавливается
    
    - `Access denied for user 'root'` — пароль root в `.env` поменяли после создания базы. База помнит
      старый: вписываем его или меняем пароль внутри базы.
    - `No such file or directory` — копии за эту дату нет: `ls /srv/backup/mariadb`.

    Слов стало в полтора раза больше, 144 против 94: добавились команды, таблица и вторая ошибка. Зато путь к копиям виден во второй строке, команду копируют целиком, ошибку находят поиском по её тексту.

    Как проверить

    • Читаем подряд одни заголовки. Получился план страницы — хорошо; получилось «Описание, Настройка, Прочее» — заголовки переписываем.
    • Даём текст человеку с одним из вопросов и смотрим, как он ищет. Пробежал по заголовкам и показал ответ — хорошо; начал читать подряд с первой строки — ответ спрятан.
    • Ищем на странице Ctrl+F по тексту ошибки из раздела «Если не работает» — строка с ошибкой должна начинаться с неё.

    Если не работает

    Заголовки есть, а нужное всё равно ищут подряд

    Причина
    Заголовки называют тему («Восстановление»), а не отвечают: из них не видно, что внутри и где ответ.
    Делаем
    В заголовок — суть раздела: «Восстановление за 4 шага», «Если копия не восстанавливается» («Заголовок говорит, что внутри»).

    Список из восьми пунктов читают хуже абзаца

    Причина
    В одном списке смешаны шаги, факты и предупреждения — у пунктов разная природа, и глаз не понимает, что перед ним.
    Делаем
    Шаги — нумерованным списком, факты — таблицей или своим списком, предупреждение — отдельно («Дробление текста»).

    После переделки текст стал вдвое длиннее

    Причина
    К каждому пункту добавились вступления и пересказ заголовка.
    Делаем
    Первая фраза раздела отвечает, а не повторяет заголовок; связки «далее», «также» вычёркиваем.