terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b97edf9f578455eb9dda6f0c6712da597f2fe2bc
tf_provider/HISTORY/SONNET/2026-08-10_docs_ux_analysis.md
T

11 KiB
Raw Blame History

Ответ Соннета: Анализ 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 строки:

.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 в <details> с заголовком "Справка (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 (в <details> 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 (не в <details>)
    Сейчас Full в раскрывашке — правильно. Но заголовок Minimal example — only required parameters на английском среди русского контента — резает глаз. Перевести.
  • Добавить комментарии в код: # Выберите из: 1, 3, 5 для параметров с value_list — LLM уже обогащает, но это должно быть в HCL-примере тоже.
  • Outputs usage: сейчас шаблонные строки с baza. Показать реальные ключи из cloud snapshot если есть: 
    # 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 в <details> 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 обернуть в <details><summary>Справка (MAN)</summary>
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. Не скрывать пример в <details> — сейчас Full example скрыт, это правильно. Minimal должен быть ОТКРЫТ и первым.
  5. Не добавлять JS-фильтрацию на index — mkdocs search уже умеет фильтровать; второй поиск создаёт путаницу.

Ключевой вывод: Самое больное место — отсутствие sidebar и нечитаемый MAN. Эти два изменения (по 3 строки CSS) дадут 80% UX-эффекта. Остальное — итеративно.

Reference in New Issue View Git Blame Copy Permalink