Предложения по руководству S3R¶
Руководство S3R прочитано глазами инженера эксплуатации, который видит плагин впервые (10–11.11.2026). По существу оно точное и полное: почти на каждый возникший вопрос ответ в тексте нашёлся. Трудность в другом — найти и понять ответ тяжело. Здесь описано, почему так получается, что предлагается изменить и как руководство переписано.
Вопросы, которые возникли при чтении, с развёрнутыми ответами и 24 замечаниями к тексту собраны на странице Вопросы читателя.
Что посмотреть¶
Руководство переписано целиком в предлагаемом виде: 41 страница в пяти разделах вместо одной.
| Раздел | Для чего | С какой страницы начать |
|---|---|---|
| Устройство | Понять до установки: что где хранится, от чего и как защищены данные | Устройство плагина, Избыточность и домены отказа |
| Установка | Выполнить по шагам | Требования и расчёт ресурсов |
| Работа с S3 | Подключить клиент | Учётные данные |
| Эксплуатация | Одна задача — одна страница | Отказы и восстановление |
| Справочник | Найти по слову | Конфигурация, Глоссарий |
Прежний вид — действующая страница на портале.
Факты при переписывании не менялись. Всё, что при этом разошлось с кодом плагина или с другой страницей, оставлено в формулировке руководства и собрано на странице Расхождения: 33 пункта для разработчиков.
Что мешает читать¶
1. Одна страница на всё. 6500 строк исходного текста и больше двухсот заголовков; оглавление не помещается на экран. Установка, устройство, справочник S3, администрирование, консоль и таблицы идут подряд. Ссылку «посмотри про замену узла» дать трудно; поиск по сайту приводит на страницу, а не к ответу.
2. Термины используются раньше, чем определяются. «Площадка», «владелец группы», «участник», «позиция», «ярус», «карта размещения» встречаются на первых двух экранах, а объясняются через тысячу строк или нигде. В глоссарии нет «площадки», «владельца», «раскладки», «поддомена». «Домен отказа» означает три разные вещи. «Хранилище полос» и «хранилище фрагментов» — одно и то же.
3. Смешаны четыре рода текста. В одном разделе стоят объяснение устройства, инструкция,
справочная таблица и разбор отказа. Пример: в «Кворуме записи» на второй странице описаны строки
таблицы s3r_t<N>_resync, а читатель ещё не знает, что такое группа. Тому, кто хочет понять, мешают
детали; тому, кто ищет параметр, мешают рассуждения.
4. Устройство описано словами реализации. «Передача обращений от среды выполнения Tokio
транзакционному потоку TX» — это назначение сервиса s3r_meta в таблице состава. Что сервис делает
для остального плагина (выполняет обращения к таблицам), не сказано.
5. Важные следствия спрятаны. То, что при нескольких площадках отказ узла навсегда лишает площадку копии его объектов, написано в примечании после таблицы третьего примера. Что делать, если на площадке нет другой группы, — в другом разделе.
6. Пропущены процедуры, которые оператор выполнит. Нет ребутстрапа инстанса, хотя роль Ansible
и оператор Kubernetes делают его одной командой, а для S3R это полное переформатирование дисков
инстанса. Отладочные backend и fs_root стоят в общей таблице настроек без предупреждения.
7. Числа без происхождения. «Окно из 64 полос», «двадцатая часть предела», k + m ≤ 64
читаются как настройки, хотя это константы формата.
Что предлагается¶
Разбить на страницы¶
По образцу Radix (plugins/radix/), в пять разделов по назначению текста: понять, установить,
пользоваться, эксплуатировать, найти.
Правило: страница одного рода. В «Устройстве» нет последовательностей команд, в «Установке» и «Эксплуатации» нет рассуждений (ссылка на «Устройство»), в «Справочнике» только факты в одинаковом формате. Страница «Устройства» начинается с блока «Коротко» и вводит свои термины до того, как ими пользуется. Всё, что ведёт к потере данных или простою, стоит выноской в начале раздела.
После разрезки разделы переставлены по назначению: процедуры собраны в «Эксплуатации», объяснения — в «Устройстве», справочные таблицы — в «Справочнике». Что именно переехало, перечислено в конце страницы Расхождения.
Сделать глоссарий рабочим¶
- Статья глоссария — заголовок с якорем, как в глоссарии Picodata, а не строка таблицы. Тогда на термин можно сослаться, и ссылку проверяет сборка сайта. В примере так уже сделано.
- При первом упоминании термина на странице — ссылка на статью.
- Добавить 14 недостающих статей и исправить две: «Домен отказа» и «Очередь ресинхронизации».
- Читательский глоссарий и таблицу терминов для авторов (
doc/guide/glossary.mdв репозитории плагина) вести из одного источника. - «Хранилище полос» и «хранилище фрагментов» — выбрать один термин. «Карту размещения» оставить за
столбцом
placements, а таблицы называть «таблицы групп размещения и дисков».
Дописать и исправить по содержанию¶
| Что | Где | Замечание на странице вопросов |
|---|---|---|
| Раздел «Ребутстрап инстанса»: шаги, отличие от перезапуска, предупреждение о переформатировании дисков, условия, критерий завершения | admin/nodes.md |
21, 22 |
| Что происходит, если на площадке нет другой группы | concepts/placement_groups.md |
11 |
Противоречие о состоянии копии на площадке: «отдельного состояния нет» и pending/live |
concepts/site_replication.md |
12 |
backend и fs_root — вынести из таблицы настроек в примечание «для разработки» |
reference/configuration.md |
23 |
| Происхождение констант — одной фразой при каждой | по месту | 13 |
| Очередь ресинхронизации — убрать подробности из пути записи в фоновые процессы | concepts/background.md |
14 |
| Версия Picodata в таблице совместимости расходится с той, на которой плагин работал на стенде | index.md |
4 |
Рисунок для раскладки instance и для отказа узла при нескольких площадках |
concepts/redundancy.md |
18 |
Как проверялась переписанная страница¶
Страница «Избыточность и домены отказа» проверялась чтением с нуля: читатель без знания S3R читает только её и отвечает на 30 контрольных вопросов — 10 на понимание формулировок, 8 «верно или неверно», 8 задач по топологии, 4 о впечатлении. Читателем был ИИ-агент, которому доступна только страница. После каждого круга текст правился по ошибкам и местам, которые пришлось перечитывать.
| Круг | Читатели | Верных ответов из 26 | Ответа нет в тексте | Оценка читателя |
|---|---|---|---|---|
| 1 | инженер эксплуатации, 4 вопроса | 3 из 4 | 1 | — |
| 2 | инженер эксплуатации; прикладной разработчик | 22 у обоих, ещё 3 неполных | 1 (у обоих один и тот же) | 4 и 4 из 5 |
| 3 | прикладной разработчик | 26, из них 3 с оговоркой «в тексте не всё» | 0 | 4 из 5 |
До пятёрки читателю третьего круга не хватило уверенности в правилах выбора раскладки и в том, зачем арбитр при двух площадках; после круга добавлены блок «Коротко», оговорка к выбору раскладки и пояснение о создании групп. Четвёртый круг не проводился. Остальные страницы так не проверялись.
Читатели просили то, чего на странице нет намеренно: рекомендацию «при таком оборудовании берите
такую топологию», выбор k и m, расчёт ёмкости, коды ответов клиенту при каждом отказе. Это
материал для install/planning.md и admin/failures.md.
Что вскрылось при переписывании¶
- Таблицы отказов в руководстве говорят только о чтении. Для записи группе нужно больше участников
(
k + m − write_tolerance), и это описано отдельно, в «Кворуме записи». Оператор, читающий «узел: доступны», решит, что запись тоже идёт. - Рекомендация «
k + m + 1доменов отказа» верна, когда узел даёт группе одного участника. При нескольких дисках на узел число другое; точное правило нужно получить у разработчиков. - Случай «инстансы не объявили домен, диски объявили поддомены» в руководстве есть только строкой в
списке примеров. Два читателя из двух без неё решили, что кластер молча выберет раскладку
instance.
Как это сделано¶
Сайт собран из исходников портала документации: ветка от master репозитория core/picodata
(коммит a55847e от 11.11.2026), тема, стили и проверки сборки те же.
- Страница
docs/docs/plugins/s3r.mdразрезана на страницы скриптом: текст внутри разделов не менялся, внутренние ссылки переведены на новые адреса, якоря сохранены. - Первые страницы («Устройство плагина», «Избыточность и домены отказа», глоссарий, начальная) написаны вручную.
- Остальные страницы переписаны по единым правилам шестью ИИ-исполнителями, по одному на раздел. Условие: факты не менять и не терять, расхождения не исправлять, а выносить в отчёт.
- После переписывания проверено скриптом: из 1320 идентификаторов исходного текста (параметры,
таблицы, метрики, маршруты, сообщения журнала) на месте все, кроме намеренно убранной
s3r_drain_stalled; из 101 примера кода 96 совпадают дословно, пять изменены по форме.
Полная сборка портала из этой ветки в строгом режиме (mkdocs build -s, как в CI) проходит без
предупреждений. Здесь в навигации оставлен только S3R, счётчики посещений отключены. Ветка
локальная, в GitLab не отправлялась.
Чего не сделано. Человек переписанные страницы целиком не читал. Читателями проверялась только страница об избыточности. Утверждения, которые исполнители добавили по коду, перечислены в «Расхождениях» и требуют подтверждения разработчиков.
Что нужно решить¶
- Источник и PDF. Руководство ведётся одним файлом
doc/guide/s3r-guide-ru.mdв репозитории плагина, из негоmake guideсобирает PDF для поставки, и оно же попадает на портал. Разбивка требует решить, где источник: несколько файлов вdoc/guide/и сборка PDF из них по списку (правкаtools/doc/render_pdf.py), либо разбивка только при публикации на портал. Первое проще сопровождать, второе не трогает сборку. Рекомендация — первое. - Кто вычитывает. Переписанный текст нужно прочитать автору руководства и разработчикам: по разделу на человека, начиная с «Устройства» и «Эксплуатации».
- Что делать с расхождениями. 33 пункта на странице Расхождения: часть — ошибки руководства, часть — возможные ошибки сверки. Ребутстрап на стенде с S3R не прогонялся — раздел о нём нужно писать после прогона.