# Ответ Соннета: Анализ UX документации Nubes Terraform Provider **Дата:** 2026-08-10 **Вопрос:** см. prompt_for_sonnet_docs_ux.md **Ответчик:** Claude Sonnet --- ## TL;DR Документация функционально корректна, но навигация сломана для нового пользователя — он не может найти нужный ресурс без знания URL. Три приоритета: восстановить sidebar, сделать главную страницу рабочей, поднять размер шрифта MAN. --- ## 1. Общая оценка **Хорошо:** - YAML → Markdown пайплайн — надёжная основа, параметры актуальны - Cloud snapshot для `state_out_flat` / `vault_secrets` — уникальная ценность, ни у кого нет - Dual example (minimal + full) — правильный выбор **Плохо:** - Боковые панели скрыты → юзер попадает на страницу и не знает как вернуться к другим ресурсам - `font-size: 0.62rem` для MAN — нечитаемо, создаёт впечатление "broken UI" - Версия в URL, но не в UI → юзер не уверен смотрит ли он актуальное - Индексная страница — голая таблица из 43 строк без группировки и фильтрации --- ## 2. Рекомендации по блокам ### A. Навигация **A1 — Навигация между ресурсами:** Лучший вариант — вернуть левый sidebar с категориями. 43 ресурса легко разбиваются на группы: - **Базы данных**: postgres, mysql, redis, mongodb, ... - **Очереди**: kafka, rabbitmq, activemq, ... - **Хранилище**: s3, swift, ... - **K8s**: kubernetes, helm, ... - **VMware**: vdc, vm, ... - **Приложения**: lucee, nodejs, flask, ... - **Сеть/прочее**: остальное Sidebar с категориями даёт ориентацию за 3 секунды. Поиск mkdocs (`search`) — бесплатный бонус. **A2 — Вернуть sidebar:** Да. Убрать из `extra.css` строки: ```css .md-sidebar--primary { display: none !important; } ``` Правый sidebar (TOC) убрать только для страниц ресурсов — там он бесполезен. Реализуется через meta-tag `hide: [toc]` в frontmatter генерируемых файлов. **A3 — Быстрый поиск:** - Включить встроенный поиск mkdocs-material (`search` plugin) - В `IndexMD()` добавить категории как `## Базы данных`, `## Очереди` — тогда sidebar mkdocs покажет дерево --- ### B. Дизайн страницы ресурса **B1 — MAN font-size:** Поднять с `0.62rem` до `0.78rem` — достаточно компактно, но читаемо. Заодно обернуть MAN в `
` с заголовком "Справка (MAN)" — DevOps обычно не читает MAN, ему нужны параметры. **B2 — Структура страницы:** Текущий порядок (MAN в начале) — неоптимален. Предлагаю: ``` 1. Заголовок + Inline nav 2. Краткое описание (1-2 строки из ServiceDisplayName + первый абзац MAN) 3. Minimal example (СРАЗУ — копируй и пробуй) 4. Create params (таблица) 5. Outputs (state_out_flat + vault_secrets) 6. MAN (в
collapsed) ``` DevOps хочет пример → понял структуру → посмотрел параметры. MAN читает если застрял. Это изменение в `buildManualPage()` — перенос `buildExamplePage()` фрагмента вверх. Либо создать новый `buildCombinedLandingPage()`. **B3 — Версия в UI:** Добавить в `buildHeader()`: ``` # Resource nubes_postgres · v5.0.5 · Service ID: 90 · PostgreSQL ``` `version` уже передаётся в `ResourceDocs()` — просто прокинуть в `buildHeader()`. --- ### C. Таблицы параметров **C1 — Колонки таблиц:** Текущие колонки: `Code | Type | Description | Constraints`. Добавить `Required` и `Default`: ``` | Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения | ``` `Required` и `Default` уже есть в данных (`SplitParams()` их разделяет), просто не выводятся в единой таблице. Убрать разделение на две таблицы — одна таблица с колонкой Required проще для чтения. **C2 — Вложенные параметры (map-fixed):** Текущий вариант (`### clusterConfiguration` → отдельная таблица) — приемлем. Улучшить: добавить ссылку-якорь в основной таблице: ``` | clusterConfiguration | map-fixed | [Развернуть ↓](#clusterconfiguration) | ... | ``` Так юзер понимает что кликнуть. Реализуется в `renderParamTable()` + `renderNestedParams()`. --- ### D. Примеры **D1 — Страница Example:** - Поменять местами: Minimal example → Full example (не в `
`) Сейчас Full в раскрывашке — правильно. Но заголовок `Minimal example — only required parameters` на английском среди русского контента — резает глаз. Перевести. - Добавить комментарии в код: `# Выберите из: 1, 3, 5` для параметров с value_list — LLM уже обогащает, но это должно быть в HCL-примере тоже. - Outputs usage: сейчас шаблонные строки с `baza`. Показать реальные ключи из cloud snapshot если есть: ```hcl # PostgreSQL connection string: # nubes_postgres.baza.state_out_flat["internalConnect.master"] ``` --- ### E. Общие рекомендации **E1 — Чего не хватает:** 1. **Lifecycle warning** — блок про `suspend_on_destroy` сейчас внизу create params мелким шрифтом. Это КРИТИЧНАЯ информация (пользователь может случайно "удалить" БД). Поднять выше, оформить как `!!! danger` admonition. 2. **Связанные ресурсы** — PostgreSQL → пример связки с Lucee/NodeJS уже есть в `buildOutputsPage()`, но только для service_id=90. Обобщить через теги в YAML. 3. **Changelog** — нужен, но это отдельная задача (нужно хранить diff между версиями YAML). **E2 — Приоритеты:** Quick wins (высокий эффект, минимум кода): 1. Убрать `display:none` с primary sidebar + включить search 2. MAN font-size 0.62rem → 0.78rem 3. Версия в buildHeader() 4. Добавить категории в IndexMD() + _nav_fragment.yml --- ## 3. Приоритизированный план действий **Phase 1 — Quick wins (1-2 дня, 1 разработчик)** 1. `extra.css`: убрать `display:none` для primary sidebar 2. `extra.css`: MAN font-size `0.62rem` → `0.78rem` 3. writers.go: прокинуть `version` в `buildHeader()` 4. `IndexMD()`: добавить категорийные заголовки (требует маппинга service → category) 5. `WriteNavFragment()`: группировка по категориям в `_nav_fragment.yml` **Phase 2 — Структура страницы (3-5 дней)** 6. Новый порядок секций: пример → параметры → MAN в `
` 7. Объединить required/defaults в одну таблицу с колонкой Required 8. Lifecycle warning → admonition `danger` **Phase 3 — Таблицы и примеры (1 неделя)** 9. Якори для вложенных параметров 10. Реальные ключи из cloud snapshot в HCL-примерах 11. Перевести заголовки примеров на русский **Долгосрок (отдельный эпик)** 12. Changelog между версиями 13. Теги для связанных ресурсов --- ## 4. Конкретные предложения по коду | Файл | Изменение | |------|-----------| | extra.css | Убрать строки `display: none !important` для обоих sidebar; MAN `.man-content` `font-size: 0.78rem` | | `writers/writers.go`: `buildHeader()` | Добавить `version` параметр, вывести в заголовок | | `writers/writers.go`: `IndexMD()` | Принять маппинг `categoryMap map[int]string`, выводить заголовки `## Category` | | `writers/writers.go`: `buildCreateParamsPage()` | Единая таблица Required + Default с колонкой Required (bool); lifecycle → admonition | | `writers/writers.go`: `buildManualPage()` | MAN обернуть в `
Справка (MAN)` | | mkdocs.yml | Включить `search` plugin | --- ## 5. Антипаттерны — что НЕ делать 1. **Не делать многоуровневую sidebar по операциям** — `Manual / Create params / Modify params` в sidebar превратит дерево в 43×6=258 пунктов. Только верхний уровень в sidebar, внутри — inline nav. 2. **Не трогать LLM prompt ради структуры** — структура страниц это Go-генератор, не LLM. LLM только обогащает тексты. 3. **Не делать HTML-таблицы** — Markdown-таблицы уже работают; HTML нужен только для сложных случаев (`lifecycle-note` div — допустимо). 4. **Не скрывать пример в `
`** — сейчас Full example скрыт, это правильно. Minimal должен быть ОТКРЫТ и первым. 5. **Не добавлять JS-фильтрацию на index** — mkdocs search уже умеет фильтровать; второй поиск создаёт путаницу. --- **Ключевой вывод:** Самое больное место — отсутствие sidebar и нечитаемый MAN. Эти два изменения (по 3 строки CSS) дадут 80% UX-эффекта. Остальное — итеративно.