Документирование с AI: От кода к понятному тексту

'Документация? Потом напишу.' Это 'потом' никогда не наступает. AI меняет экономику: сгенерировать документацию из кода занимает минуты, не часы. Барьер падает, документация появляется.

• **JSDoc/Docstrings**: Из функции → полная документация с примерами
• **README**: Из разрозненной информации → структурированный документ
• **ADR**: Фиксация архитектурных решений и их причин
• **Поддержка**: Найти расхождения между кодом и документацией

Предварительные знания

• Prompt Engineering: The Art of Asking the Right Questions

Генерация документации из кода

Документация устаревает. Код меняется - документация остаётся прежней. AI помогает генерировать документацию из актуального кода.

**Промпт для документации кода:** 'Напиши JSDoc/docstring для этой функции. ``` [код] ``` Включи: - Описание что делает - Параметры с типами - Возвращаемое значение - Примеры использования - Throws (какие ошибки)'

**Проверяй сгенерированную документацию!** AI может неправильно понять логику или упустить важные детали.

README и project documentation

README - визитная карточка проекта. AI помогает создать структурированный README из разрозненной информации.

**Промпт для README:** 'Напиши README.md для проекта. Информация: - [Что проект делает] - [Технологии] - [Как установить] - [Как запустить] - [Структура папок] Формат: профессиональный, с badges, ToC, примерами.'

**Другие типы документации:**

• **API docs**: 'Сгенерируй OpenAPI spec из этих endpoints'
• **Changelog**: 'Напиши changelog из этих коммитов'
• **Migration guide**: 'Напиши guide миграции с v1 на v2'
• **Troubleshooting**: 'FAQ из этих issues'

Architecture Decision Records

**ADR (Architecture Decision Record)** - документ, объясняющий почему было принято решение. AI помогает структурировать и записать решения.

**Промпт для ADR:** 'Напиши ADR для решения: [описание]. Контекст: [почему нужно было решать] Рассмотренные варианты: [A, B, C] Выбор: [что выбрали] Причины: [почему] Формат: стандартный ADR template.'

**Зачем ADR:**

• Новый член команды понимает 'почему так'
• Не повторяешь обсуждение через год
• Документирует trade-offs
• Помогает принимать похожие решения

Поддержка документации

Главная проблема документации - она устаревает. AI помогает синхронизировать документацию с кодом.

**Промпт для проверки актуальности:** 'Вот код: ``` [текущий код] ``` Вот документация: ``` [текущая документация] ``` Что устарело? Что добавить? Что удалить?'

**Стратегии поддержки:**

• **Docs as Code**: Документация рядом с кодом, ревьюится вместе
• **Generated docs**: JSDoc/Swagger генерируются из кода
• **Periodic review**: Раз в спринт проверять актуальность
• **AI lint**: Автоматическая проверка соответствия

**Лучшая документация - та, которая не нужна.** Сначала: понятные имена, простой код. Потом: документация для того, что незакономерно из кода.

Ключевые идеи

• **AI генерирует документацию из кода** - JSDoc, README, API docs
• **ADR**: Документируй не только 'что', но и 'почему'
• **Проверяй сгенерированное**: AI может неправильно понять логику
• **Поддержка**: AI находит расхождения между кодом и документацией
• **Docs as Code**: Документация рядом с кодом, ревьюится вместе

Куда дальше?

Документация - часть профессиональной разработки. Дальше:

• Обучение с AI — Документация как инструмент обучения
• Code Review с AI — Ревью документации вместе с кодом
• AI для архитектуры — ADR как результат архитектурных обсуждений

Вопросы для размышления

• Какой код в твоём проекте больше всего нуждается в документации?
• Есть ли у вас ADR? Если нет - какие решения стоило бы задокументировать?
• Попробуй сгенерировать README для текущего проекта. Что AI упустил?

Связанные уроки

• se-01