Files

T

Repinoid 2c196e8cc8 docs(history): раскладка HISTORY по тематическим папкам (75 файлов)

Было: 41 файл в корне HISTORY/ + авторские папки OPUS/ и SONNET/ (34 файла).
Стало — тематическая нумерация в стиле NOTES/ (10_, 20_, …):

  10_reviews/    ревью кода и разборы от LLM (2)
  20_releases/   заливки версий в реестр, чистки реестра, нумерация версий (8)
  30_provider/   ядро провайдера: архитектура, модификаторы, UUID, nested (6)
  40_generator/  генератор YAML/спеки, формат MAN (3)
  50_docs/       пайплайн документации, навигация, публикация, хостинг S3 (9)
  60_stands/     стенды и примеры: CRUD, FullPipe, Штурвал, TEST_STAND (7)
  70_infra/      реестр, API Gateway, DDoS-Guard, VPN/213, зеркала (4)
  90_llm/        диалоги и промпты с LLM вне тематики: OPUS/, SONNET/, gemini/ (34)

OPUS/ и SONNET/ перенесены как есть в 90_llm/ — чтобы не рвать пары
«бриф → ответ» внутри диалогов. Все переносы — через git mv (история сохранена).
Перед правкой: TMP/backup_2026-10-02/HISTORY_before_restructure.tar.gz.
Перекрёстные ссылки обновляются следующим коммитом.

2026-10-02 07:35:32 +03:00

7.3 KiB

Raw Blame History

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: Структура страниц

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/ и скажи: что непонятно, что раздражает, чего не хватает.

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

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

7.3 KiB Raw Blame History Unescape Escape