tf_provider/HISTORY/SONNET/docs_improvement_briefing.md

Sonnet Briefing: анализ и улучшение документации провайдера

Цель: изучить КАЖДЫЙ шаг генерации документации и предложить конкретные улучшения, чтобы пользователю было понятно и удобно работать с каждым ресурсом.

---

⛔ Файлы — ПРОЧИТАТЬ ОБЯЗАТЕЛЬНО ВСЕ

Генераторы

#	Файл	Что смотреть
1	TOOLS/docs-generator/main.go	весь main — как вызывается, какие флаги
2	TOOLS/docs-generator/internal/writers/writers.go	ВСЕ функции. Особенно: buildCreateParamsPage, buildModifyParamsPage, buildOutputsPage, buildExamplePage, buildManualPage, renderParamTable, renderNestedParams, htmlToMarkdown, formatParamOrBlock
3	TOOLS/docs-generator/internal/types/	структуры YAML-спеки

LLM-обработка

#	Файл	Что смотреть
4	TOOLS/scripts/05_generate_docs_llm.py	весь скрипт — как вызывается LLM, промпт, как парсится ответ
5	docs/LLM_DOCS_GENERATION.md	архитектура, правила для LLM

Результаты генерации (примеры)

#	Файл	Что смотреть
6	generated/test/docs/postgres_params_create.md	RAW-вывод docs-generator (без LLM)
7	generated/test/docs_llm/90_postgres.md	ПОСЛЕ LLM-обработки
8	generated/test/docs/postgres.md	главная страница (MAN)
9	generated/test/docs/postgres_example.md	HCL пример
10	generated/test/docs/postgres_outputs.md	выходные параметры
11	generated/test/docs/postgres_ops.md	список операций

---

Текущий пайплайн (3 шага)

YAML-спеки
  → docs-generator (Go) → raw .md с HTML-таблицами
  → LLM (gpt-oss-120b, по одному файлу) → улучшенные .md
  → mkdocs-material → статический сайт → S3

---

Что видит пользователь СЕЙЧАС (пример: postgres_params_create.md)

До LLM (raw):

<table><thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Description</th><th>Constraints</th></tr></thead>
<tr><td>788</td><td><strong><code>cluster_configuration</code></strong></td><td><code>map-fixed</code></td><td></td><td></td></tr>

• Колонка ID (техническая, пользователю не нужна)
• Английские заголовки (Code, Description, Constraints)
• Пустые ячейки Description
• Raw value_list= в Constraints

После LLM:

| clusterConfiguration | map-fixed | да | — | — |

• Русские заголовки ✅
• ID убран ✅
• Но: пустые Description (—), value_list не раскрыт

---

Проблемы (что нужно улучшить)

1. Пустые описания параметров

Многие параметры в выводе имеют — в колонке «Описание». Если сервис предоставил descr или man в YAML — он должен быть в документации.

2. Технические колонки

• Колонка «Constraints» показывает value_list=1, 3, 5, 7 вместо читаемого «Допустимые значения: 1, 3, 5, 7»
• Колонка «Default» показывает пустую строку вместо «нет» или «—»
• ID параметров виден в raw-версии, но нужен ли он вообще?

3. MAN-секция (service_man)

Это HTML-строка с полным руководством от облачного провайдера. Она обрабатывается htmlToMarkdown() — regex-заменами. Часто результат нечитаемый: сломанные списки, потерянные ссылки, HTML-мусор.

4. HCL-примеры

buildExamplePage генерирует пример с ВСЕМИ параметрами (required + default). Это гигантский манифест на 100+ строк. Может, показывать сначала минимальный working example, а полный — отдельно?

5. Навигация

На каждой странице — строка навигации из 6 ссылок. Занимает место, дублируется. Может, сделать сайдбар или хлебные крошки?

6. LLM-промпт (05_generate_docs_llm.py)

Промпт просит «улучшить формулировки», но:

• Не просит раскрывать value_list в читаемый вид
• Не просит добавлять «почему» и «зачем» к параметрам
• Не использует service_man как дополнительный контекст для обогащения описаний
• Обрабатывает по одному файлу — теряет контекст между страницами

---

Вопросы

Q1: Структура страниц

Текущая: Manual | Create params | Modify params | Outputs | Ops | Example. Удобно ли это? Что переставить/добавить/убрать? Может, всё на одной странице с якорями?

Q2: HTML-таблицы vs Markdown-таблицы

Сейчас raw — HTML, LLM конвертирует в Markdown-таблицы. Оставить Markdown? Или HTML-таблицы лучше (CSS, выравнивание)?

Q3: LLM-промпт

Как улучшить промпт чтобы:

• description параметров наполнялся из service_man где возможно
• value_list показывался читаемо
• empty cells говорили «не указано» а не «—»

Q4: HCL-примеры

Минимальный пример + полный? Или только минимальный? Или только полный?

Q5: Постраничная vs одностраничная документация

7 .md файлов на сервис. Это норм или перебор? Может, генерировать один README.md на сервис со всем внутри?

Q6: Что ещё можно улучшить для UX?

Посмотри на любые 2-3 страницы из generated/test/docs_llm/ и скажи: что непонятно, что раздражает, чего не хватает.

---

Ожидаемый ответ

1. Анализ текущего состояния: что хорошо, что плохо (с конкретными примерами из файлов)
2. Конкретные предложения по каждому из 6 вопросов
3. Unified diff предлагаемых изменений в writers.go и 05_generate_docs_llm.py
4. Пример одной страницы «как должно быть» для postgres (хотя бы params_create)