“Naeel”
c9a881aa84
- value_list → читаемый текст (Допустимые значения) - regex → описание формата - пустые описания → заполнять из MAN - группы map-fixed → 1 предложение о содержимом - операции без описания → шаблоны - MAN-контекст для params/ops файлов - max_tokens 4096 → 8192 - вывод в docs_llm/ вместо перезаписи docs/
131 lines
7.3 KiB
Markdown
131 lines
7.3 KiB
Markdown
# 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):
|
||
```html
|
||
<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)
|