Дизайн таблиц документации — ответы Соннета и итоговый план

Консультация с 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%

Моё мнение

Соннет дал очень толковые ответы. Главные инсайты для меня:

★ красная звёздочка вместо колонки Required — это убивает двух зайцев: семантически точнее (★ = «обязательно», а не ✓ = «ок»), и экономит колонку. Я до этого думал про ✓ и не догадался до ★.
Default выше Constraints — логично. Я ставил Constraints наравне с Default, но реально юзер сначала смотрит дефолт. Constraints — fallback.
line-clamp(2) — компромисс между «прятать» и «показывать всё». 73% описаний влезут, CTRL+F работает, вертикальный ритм не ломается. Лучше чем сворачивать.
Кнопка копирования — я упустил. Самая частая операция юзера — скопировать имя параметра. Иконка ⧉ при hover — микрофича с огромным эффектом.
Порядок строк — required первыми. Тоже упустил. Сейчас они вразнобой из YAML.

Единственное с чем не согласен: поиск. Соннет говорит «не нужен, Ctrl+F хватает». Но когда параметров 25+ и они называются access_configuration_allow_list_ip_space_master, Ctrl+F неудобен. Фильтр с debounce в 5 строк JS — не переусложнение, а реальная помощь. Но это на потом, не в первую очередь.

5.8 KiB Raw Blame History Unescape Escape