76 lines
5.8 KiB
Markdown
76 lines
5.8 KiB
Markdown
# Дизайн таблиц документации — ответы Соннета и итоговый план
|
||
|
||
> Консультация с Claude Sonnet от 2026-07-18 по дизайну страниц параметров Terraform-провайдера Nubes.
|
||
> Полный контекст и вопросы: см. историю чата.
|
||
|
||
---
|
||
|
||
## Ответы Соннета (кратко)
|
||
|
||
| # | Вопрос | Ответ Соннета |
|
||
|---|--------|--------------|
|
||
| 1 | Приоритеты правильные? | Да, но Default должен быть ВЫШЕ Constraints. Юзер сначала смотрит Default, и только если не устраивает — лезет в Constraints |
|
||
| 2 | Пропорции ширин? | Code **20-22%**, Default **12%**, Description **32-40%**, Constraints **29-31%** |
|
||
| 3 | Убирать ID? Type → иконки? | **ID — убрать совсем.** Type — заменить иконками-баджами (`123`, `"…"`, `{…}`, `[…]`) в ячейке Code. Экономия колонки |
|
||
| 4 | Required: ✓ или ★? | **Красная ★ перед Code.** Универсальная конвенция (HTML-формы, Swagger). Экономия колонки |
|
||
| 5 | Description прятать? | **line-clamp(2) с кнопкой «▼ ещё».** Короткие (<80 символов) показывать полностью |
|
||
| 6 | Constraints — monospace? | **Да.** `font-family: monospace`, `overflow-wrap: anywhere`. `break-all` рвёт regex нечитаемо |
|
||
| 7 | Поиск по параметрам? | **Не нужен.** ~16 параметров на сервис, Ctrl+F браузера хватает |
|
||
| 8 | Цветовое кодирование строк? | **Да, тонко.** Required: `#fffbf0`, Nested: `padding-left + #f8f8f8`, Zebra: `#fafafa`/`#fff` |
|
||
| 9 | Sticky thead? | **Да.** `position: sticky; top: 0` |
|
||
| 10 | Что упустили? | **Кнопка копирования Code** (⧉ при hover). **Порядок строк** (required первые). ~~Мобильный вид~~ — не актуально, аудитория только десктоп |
|
||
---
|
||
|
||
## Итоговый план (объединённое мнение Соннета + моё)
|
||
|
||
### Этап 1 — быстро, только CSS (сделать сейчас)
|
||
|
||
| # | Что | Как |
|
||
|---|---|---|
|
||
| 1 | ★ вместо колонки Required | CSS: скрыть текст, `::before { content: "★"; color: #e74c3c; }` перед Code |
|
||
| 2 | Убрать ID | `display: none` на `th:nth-child(1)`, `td:nth-child(1)` |
|
||
| 3 | Monospace для Constraints | `font-family: monospace`, `overflow-wrap: anywhere` |
|
||
| 4 | Sticky thead | `position: sticky; top: 0; z-index: 1` |
|
||
| 5 | line-clamp(2) для Description | `display: -webkit-box; -webkit-line-clamp: 2` |
|
||
| 6 | Перераспределить ширины | По таблице ниже |
|
||
| 7 | Zebra striping | `tr:nth-child(even) { background: #fafafa }` |
|
||
|
||
### Этап 2 — правки генератора (позже)
|
||
|
||
| # | Что | Как |
|
||
|---|---|---|
|
||
| 8 | ★ генерировать в HTML (не CSS) | В `writers.go` добавить `★` перед Code для required |
|
||
| 9 | Иконки типов | В `writers.go`: `string` → `"…"`, `integer` → `123`, `map-fixed` → `{…}` и т.д. |
|
||
| 10 | Кнопка копирования | JS: при клике на Code копировать в буфер |
|
||
| 11 | Порядок строк | Required-параметры первыми в `renderParamTable` |
|
||
|
||
### Новые ширины колонок (после удаления ID и Required)
|
||
|
||
**Основная таблица (4 колонки):**
|
||
| Code+Type | Default | Description | Constraints |
|
||
|---|---|---|---|
|
||
| 22% | 13% | 35% | 30% |
|
||
|
||
**Nested-таблица (5 колонок, ID и Required убраны):**
|
||
| ★Code+Type | Default | Description | Constraints |
|
||
|---|---|---|---|
|
||
| 22% | 12% | 35% | 31% |
|
||
|
||
---
|
||
|
||
## Моё мнение
|
||
|
||
Соннет дал очень толковые ответы. Главные инсайты для меня:
|
||
|
||
1. **★ красная звёздочка вместо колонки Required** — это убивает двух зайцев: семантически точнее (★ = «обязательно», а не ✓ = «ок»), и экономит колонку. Я до этого думал про ✓ и не догадался до ★.
|
||
|
||
2. **Default выше Constraints** — логично. Я ставил Constraints наравне с Default, но реально юзер сначала смотрит дефолт. Constraints — fallback.
|
||
|
||
3. **line-clamp(2)** — компромисс между «прятать» и «показывать всё». 73% описаний влезут, CTRL+F работает, вертикальный ритм не ломается. Лучше чем сворачивать.
|
||
|
||
4. **Кнопка копирования** — я упустил. Самая частая операция юзера — скопировать имя параметра. Иконка ⧉ при hover — микрофича с огромным эффектом.
|
||
|
||
5. **Порядок строк** — required первыми. Тоже упустил. Сейчас они вразнобой из YAML.
|
||
|
||
Единственное с чем не согласен: **поиск**. Соннет говорит «не нужен, Ctrl+F хватает». Но когда параметров 25+ и они называются `access_configuration_allow_list_ip_space_master`, Ctrl+F неудобен. Фильтр с debounce в 5 строк JS — не переусложнение, а реальная помощь. Но это на потом, не в первую очередь.
|