Промпт для технического писателя и разработки документации

Пример входных данных (Кейс)

«В нашей компании 50 микросервисов, но документация API разрознена: где-то PDF, где-то Swagger, где-то README. Разработчики тратят часы на поиск актуальных эндпоинтов. Нужно создать единый портал документации API».

Ответ модели

1. Переформулировка и критерий успеха Задача: Консолидация документации API из разных источников в единый портал (Developer Portal). Критерий успеха: Время поиска и проверки актуальности эндпоинта сокращено с «часов» до <5 минут; 100% спецификаций доступны в одном месте.

2. Варианты решения

• Static Site Generator (Docusaurus/Hugo): Плюсы — полный контроль кастомизации, Docs-as-Code. Риски — сложность настройки сборки из разных репозиториев.

• SaaS-решения (Redocly/Stoplight): Плюсы — быстрый старт, отличный UI. Риски — зависимость от вендора, стоимость.

• Self-hosted Swagger Hub: Плюсы — нативно для разработчиков. Риски — сложность организации не-API контента (гайдов, авторизации).

3. Выбранное решение и план внедрения Выбираем Docusaurus (Docs-as-Code) как наиболее гибкий и профессиональный подход техписа.

• Шаг 1 (Структура): Создание центрального репозитория портала. Настройка CI/CD для подтягивания JSON/YAML спецификаций из репозиториев микросервисов.

• Шаг 2 (Стандартизация): Внедрение линтинга (Spectral) для проверки соответствия API-дизайна гайдлайнам компании.

• Шаг 3 (Контент): Написание вводных разделов (Auth, Errors, Rate Limiting) и добавление интерактивных консолей «Try it out» через плагин OpenAPI.

4. Метрики и контроль

• Метрики: Количество обращений к документации (DAU), Time-to-first-call (время от открытия до первого успешного запроса).

• Точки: Спринт 2 — готов MVP с 5 сервисами; Спринт 4 — миграция всех 50.

5. Риски и снижение

• Риск: Документация устаревает. Снижение: Автогенерация спек из кода и блокировка Merge Request при нарушении линтинга.

...