docs: Q&A with Sonnet — UX analysis + nav merge strategy (Phase 1-3 plan)
This commit is contained in:
“Naeel”
@@ -0,0 +1,183 @@
|
||||
# Ответ Соннета: Анализ 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 в `<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 если есть:
|
||||
```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 в `<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-эффекта. Остальное — итеративно.
|
||||
@@ -0,0 +1,61 @@
|
||||
# Ответ Соннета: Как смержить nav (статический + динамический)
|
||||
|
||||
**Дата:** 2026-08-10
|
||||
**Вопрос:** Как смержить статический `nav:` (руководства) и динамический (43 ресурса по категориям) в mkdocs?
|
||||
**Ответчик:** Claude Sonnet
|
||||
|
||||
---
|
||||
|
||||
## Нет встроенного `!include` в mkdocs
|
||||
|
||||
mkdocs-material не имеет нативного механизма подключения внешних YAML-фрагментов в `nav:`. Плагины (monorepo, awesome-pages) решают другие задачи и здесь не помогут.
|
||||
|
||||
---
|
||||
|
||||
## Три варианта (по убыванию рекомендованности)
|
||||
|
||||
### Вариант 1 — Рекомендую: расширить существующий Python pre-build шаг
|
||||
|
||||
В `04_build_and_publish_docs.sh` уже есть Python-блок, который пишет `.mkdocs.tmp.yml`. Добавить туда чтение `_nav_fragment.yml` и инъекцию в `nav:`:
|
||||
|
||||
```python
|
||||
import yaml
|
||||
|
||||
nav_fragment_path = Path(docs_dir) / "_nav_fragment.yml" if docs_dir else None
|
||||
if nav_fragment_path and nav_fragment_path.exists():
|
||||
fragment = yaml.safe_load(nav_fragment_path.read_text(encoding="utf-8"))
|
||||
resources_nav = fragment.get("resources_nav", [])
|
||||
|
||||
config = yaml.safe_load(text)
|
||||
for item in config.get("nav", []):
|
||||
if isinstance(item, dict) and "Ресурсы" in item:
|
||||
item["Ресурсы"] = resources_nav
|
||||
break
|
||||
text = yaml.dump(config, allow_unicode=True, default_flow_style=False, sort_keys=False)
|
||||
```
|
||||
|
||||
**Плюсы:** ноль новых зависимостей, PyYAML уже в окружении, merge в одном месте, статические секции ("Руководства") остаются нетронутыми.
|
||||
|
||||
**Предупреждение:** PyYAML при `dump` меняет форматирование (кавычки, отступы) — это нормально для `.mkdocs.tmp.yml`, который никто не читает руками.
|
||||
|
||||
### Вариант 2: docs-generator пишет полный mkdocs.yml
|
||||
|
||||
Сделать отдельный файл `mkdocs_base.yml` (тема, плагины, CSS, статический nav — без ресурсов), Go-генератор его читает, добавляет ресурсный nav, пишет финальный mkdocs.yml.
|
||||
|
||||
**Минус:** Go-генератор становится ответственным за весь mkdocs.yml, сложнее поддерживать структуру темы/плагинов.
|
||||
|
||||
### Вариант 3: mkdocs-awesome-pages
|
||||
|
||||
Плагин создаёт `.pages` файлы в директориях и управляет порядком через них. Но `nav:` в mkdocs.yml при этом должен быть либо полностью убран, либо включать ресурсы явно — проблему merge не решает.
|
||||
|
||||
---
|
||||
|
||||
## Дополнительная проблема: guides при смене `docs_dir`
|
||||
|
||||
Когда `docs_dir` переключается на `generated/{stand}/docs_llm`, пути вида `30_registry/guides/getting-started.md` в `nav:` ломаются — этих файлов там нет.
|
||||
|
||||
**Решение:** в том же Python pre-build шаге скопировать `30_registry` в `$MKDOCS_DOCS_DIR/30_registry/` перед сборкой. Или — убрать guides из профильного nav (оставить только ресурсы).
|
||||
|
||||
---
|
||||
|
||||
**Итого:** Вариант 1 — минимальные изменения, всё уже на месте. Нужно только расширить существующий Python блок в `04_build_and_publish_docs.sh` примерно на 10 строк + скопировать `30_registry` в `docs_dir`.
|
||||
Reference in New Issue
Block a user