docs(history): раздел о синхронизации документов по итогам ревью + моя ошибка

Проверено: разделы 1-8, факты (166060 байт, сравнение разделов) — из проверок.
This commit is contained in:
Repinoid
2026-10-02 08:58:38 +03:00
parent 17350eed89
commit 4cb3645ab8
@@ -175,7 +175,37 @@ README (коммит `272d405`) — на живой странице 167 269 б
сборкой — совпала; вхождений `instanceOperations`, `errorLog`, `HISTORY/`, `crud.go`, `refsvc_find` сборкой — совпала; вхождений `instanceOperations`, `errorLog`, `HISTORY/`, `crud.go`, `refsvc_find`
— **ноль**; первый раздел — «Быстрый старт». — **ноль**; первый раздел — «Быстрый старт».
## 7. Мои ошибки в этой работе ## 7. Синхронизация README и страницы по итогам ревью владельца
> Замечание: «Я прочитаю оба источника и проверю их глазами юзера… ана­лизируй и правь и заливай».
Что было по замечаниям (все — в обоих документах, `TEST_STAND/CRUD/README.md` и
`docs/curated/crud/three_apps.md`):
1. **Рассинхрон документов** — теперь одинаковый набор и порядок разделов: «Быстрый старт»,
«Что создаётся», «Как это устроено», «Что пользователь задаёт сам», «Код приложений (git)»,
«Провайдер», «Повседневные операции», «Файлы», «Особенности этого примера», «Справка».
На странице «Структура манифестов» переименована в «Как это устроено», «Код приложений»
перенесён после «Что пользователь задаёт сам», добавлены «Повседневные операции» и «Файлы»,
«Особенности» перенесены перед «Справкой»; в README добавлены «Что создаётся», «Провайдер»,
«Особенности». Проверено пофайловым сравнением разделов: различия остались только там, где
так и должно быть — разделители `---` в README и `{{PROVIDER_SOURCE}}` / `{{VERSION}}` /
`{{NUBES_API_ENDPOINT}}` на странице (они подставляются при сборке).
2. **Ошибка в таблице env** — было «`pg_db_name` → Lucee → `testds_connectionString`,
`DATABASE_URL`»; по `apps/lucee.tf` это **составные строки подключения** из хоста, порта,
пользователя, пароля и имени базы, а `PGDATABASE` у Lucee вообще нет. Таблица исправлена,
под ней добавлено пояснение про `testds_connectionString`/`DATABASE_URL` и остальные `testds_*`.
3. **«Внутренний хост master»** — дополнено: приложения ходят к базе по внутренней сети кластера,
а сами открываются по внешним доменам.
4. **Пути репозиториев** — в таблицах приведены к тому же виду, что в `apps/locals.tf`: с `.git`.
5. **«Уникально в пределах стенда»** → «уникально внутри своего сервиса» (postgres / lucee /
flask / nodejs — у каждого свой набор имён).
6. **`postgres_conf` и остальные особенности** — теперь есть и в README (раньше были только на
странице).
Публикация: страница перезалита, живая страница 166 060 байт, `cmp` с локальной сборкой совпал.
## 8. Мои ошибки в этой работе
- Разделение `pg/` + `apps/` назвал «разделение ответственности, decoupling» — терминологически - Разделение `pg/` + `apps/` назвал «разделение ответственности, decoupling» — терминологически
неверно (это про модули кода) и заумно. Владелец: «пиши ПРАВИЛЬНО, не надо натягивать заумности». неверно (это про модули кода) и заумно. Владелец: «пиши ПРАВИЛЬНО, не надо натягивать заумности».
@@ -204,6 +234,10 @@ README (коммит `272d405`) — на живой странице 167 269 б
`apps/terraform.tfstate` регуляркой и фразу «Все команды выполняются из каталога `TEST_STAND/CRUD`», `apps/terraform.tfstate` регуляркой и фразу «Все команды выполняются из каталога `TEST_STAND/CRUD`»,
которые пользователю не нужны и ничего не дают. Владелец: «нахуя это юзеру?». Вывод: перед которые пользователю не нужны и ничего не дают. Владелец: «нахуя это юзеру?». Вывод: перед
добавлением строки отвечать себе, что читатель с ней СДЕЛАЕТ, а не «мне кажется, полезно». добавлением строки отвечать себе, что читатель с ней СДЕЛАЕТ, а не «мне кажется, полезно».
- Держал README и страницу сайта в разных состояниях: правил один документ и забывал второй,
из-за чего в них оказались разные наборы разделов и разные формулировки. Владелец: «на сайте то же
самое?» → потом «сверю и найду бред». Вывод: это один и тот же текст в двух местах — править
только парой, сразу, и сверять сравнением разделов.
- Дважды пропустил главное для читателя-новичка: **какие параметры он задаёт своими значениями** - Дважды пропустил главное для читателя-новичка: **какие параметры он задаёт своими значениями**
и **что имена/домены обязаны быть уникальными**. Пришлось напоминать владельцу. Причина одна: и **что имена/домены обязаны быть уникальными**. Пришлось напоминать владельцу. Причина одна:
писал про технику (`apply`, выходы, `creds.json`), а не про то, что нужно человеку в начале. писал про технику (`apply`, выходы, `creds.json`), а не про то, что нужно человеку в начале.