AI для написания пользовательской документации: от спецификации к руководству пользователя

Если вы когда-нибудь писали руководство пользователя к системе, которую сами же и проектировали, — вы знаете эту боль. Требования уже согласованы, архитектура утверждена, код пишется. И тут прилетает: «А где документация для пользователей?» Знакомая ситуация?

Писать документацию вручную — это часы монотонной работы: пересказывать одно и то же разными словами, думать за пользователя, предугадывать его вопросы, перечислять ограничения. LLM способна взять на себя львиную долю этой рутины. Не вместо аналитика, а вместе с ним. Давайте разберёмся, как построить такой процесс.

Зачем вообще подключать AI к документации

Работа аналитика не заканчивается на написании ТЗ. После того как требования утверждены, начинается производство артефактов: руководство пользователя, FAQ, заметки к релизу, иногда — onboarding-материалы для поддержки. Всё это вариации на тему «объясни систему человеку, который её не проектировал».

LLM здесь хороша тем, что умеет переформулировать. Возьмите сухую спецификацию — «Система должна позволять пользователю создавать заказ с указанием списка товаров и адреса доставки» — и превратите её в человеческий текст: «Чтобы оформить заказ, нажмите кнопку “Новый заказ”, выберите товары из каталога и укажите адрес доставки. Система рассчитает стоимость автоматически». Рутинно? Да. Долго? Очень. AI справляется за секунды.

Плюс к этому — системность. LLM не забудет упомянуть сценарий, который есть в спецификации, но который аналитик мог пропустить при ручном написании документации (потому что «ну это же очевидно»). Машине ничего не очевидно — она перебирает всё, что ей дали.

Как устроен процесс: от спецификации к готовому документу

Процесс можно разложить на этапы. Аналитик загружает спецификацию (или фрагмент ТЗ) в LLM, модель анализирует структуру, выделяет пользовательские сценарии, бизнес-правила и ограничения, определяет целевую аудиторию — а затем генерирует документы разного формата. После генерации — обязательная вычитка аналитиком: проверка полноты, точности и соответствия реальной системе. Только после этого документация уходит в публикацию.

graph TD
  A["Спецификация / ТЗ"] --> B["LLM: анализ структуры документа"]
  B --> C["Выделение пользовательских сценариев"]
  B --> D["Извлечение бизнес-правил и ограничений"]
  B --> E["Определение целевой аудитории"]
  C --> F["Генерация руководства пользователя"]
  D --> F
  E --> F
  C --> G["Генерация FAQ"]
  D --> G
  F --> H["Проверка аналитиком: полнота и точность"]
  G --> H
  B --> I["Формирование заметок к релизу"]
  I --> H
  H --> J["Публикация в Confluence / Wiki"]
  style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style B fill:#f0a500,stroke:#c88400,color:#fff
  style C fill:#7b68ee,stroke:#5a4db2,color:#fff
  style D fill:#7b68ee,stroke:#5a4db2,color:#fff
  style E fill:#7b68ee,stroke:#5a4db2,color:#fff
  style F fill:#50c878,stroke:#3a9a5c,color:#fff
  style G fill:#50c878,stroke:#3a9a5c,color:#fff
  style I fill:#50c878,stroke:#3a9a5c,color:#fff
  style H fill:#f0a500,stroke:#c88400,color:#fff
  style J fill:#4a90d9,stroke:#2c5f8a,color:#fff

На диаграмме видно: LLM работает не как чёрный ящик «загрузил ТЗ — получил идеальный документ». Это конвейер с промежуточными этапами и обязательной точкой контроля человеком. Аналитик остаётся в петле принятия решений — модель лишь ускоряет черновую работу.

Примечательно, что один и тот же набор сценариев и бизнес-правил питает сразу несколько выходных форматов. Это ключевая экономия: вы не пишете FAQ отдельно от руководства — вы даёте модели единый контекст, а она адаптирует стиль и фокус под каждый формат.

Промпты для разных типов документации

Каждый тип документа требует своего подхода. Универсальный промпт «напиши документацию» даст посредственный результат. Разберём три основных формата.

Руководство пользователя

Здесь нужен пошаговый стиль. Пользователь открывает документ с конкретной задачей: «Как создать заказ?», «Как отменить бронирование?». Промпт должен это учитывать.

Пример промпта:

Ты — технический писатель. На основе спецификации ниже напиши руководство пользователя для роли «Менеджер по продажам». Структура: краткое описание системы, пошаговые инструкции для каждого пользовательского сценария, раздел «Типичные ошибки и как их исправить». Стиль: нейтрально-деловой, без маркетинговых фраз. Каждый шаг начинай с глагола в повелительном наклонении.

После генерации — обязательная проверка: все ли сценарии из спецификации покрыты? Нет ли шагов, которые противоречат реальному поведению системы? Не придумала ли модель несуществующие кнопки? Последнее случается чаще, чем хотелось бы.

FAQ / Частые вопросы

FAQ — это не «придумай десять вопросов». Это извлечение того, что действительно непонятно. Хороший приём: дать модели спецификацию и попросить её представить себя пользователем, который видит систему впервые.

Пример промпта:

На основе спецификации ниже составь список из 15 частых вопросов пользователя, который впервые работает с системой. Для каждого вопроса дай краткий ответ (2-4 предложения). Сгруппируй вопросы по темам: «Начало работы», «Ограничения», «Типичные проблемы». Не придумывай вопросы, на которые в спецификации нет ответа.

Важный нюанс: если в спецификации нет информации по какому-то аспекту, LLM может её «дополнить» из своих знаний о похожих системах. Это галлюцинация. Каждый ответ FAQ должен быть верифицируем по исходной спецификации.

Заметки к релизу

Здесь главное — краткость и структура. Разработчикам и тестировщикам не нужно читать простыню — им нужен чёткий список: что нового, что сломано, что исправлено.

Пример промпта:

Составь заметки к релизу v2.3 на основе списка изменений ниже. Формат: «Новые возможности», «Исправления», «Известные ограничения». Каждый пункт — одно предложение. Технические детали сворачивай: пользователю интерфейса не нужно знать, что «поменяли ORM-запрос на findByStatus».

Что может пойти не так

Это не серебряная пуля. Есть минимум три типовые проблемы, к которым надо быть готовым.

Галлюцинации. LLM может придумать функциональность, которой нет в спецификации. Например, «система отправляет уведомление на email» — а в требованиях про email ни слова. Модель «дополнила» картину мира из своего опыта. Лечится жёстким промптом: «Не добавляй функциональность, которой нет в исходном документе. Если не уверена — напиши “не указано в спецификации”».

Потеря контекста. Если спецификация большая (30+ страниц), модель может «забыть» сценарии из середины документа и сосредоточиться на начале и конце. Лечится разбивкой: не скармливайте всю спецификацию сразу. Генерируйте документацию по разделам, а потом объединяйте. Да, дольше. Но результат точнее.

Сухой стиль. LLM по умолчанию пишет ровно. Безлико. Иногда — откровенно скучно. Исправить это можно, добавив в промпт пример целевого стиля (few-shot): покажите модели фрагмент хорошей документации из вашего проекта и попросите придерживаться такого же тона. Пара примеров творят чудеса.

Чек-лист: когда AI-документация готова к публикации

Перед тем как отдавать документ пользователям, пройдите по этому списку:

• Все пользовательские сценарии из спецификации покрыты
• Нет вымышленной функциональности (проверили каждый пункт FAQ и руководства)
• Скриншоты и названия кнопок соответствуют реальному интерфейсу
• Стиль единообразен по всему документу
• Ограничения и известные проблемы явно перечислены (а не спрятаны в середине абзаца)
• Документ прочитал хотя бы один человек, не знакомый с системой (тест на понятность)

Этот чек-лист — минимальный барьер. Если хотя бы один пункт не выполнен — документация не готова, независимо от того, насколько красиво её написала LLM.

Заключение

AI для документации — не замена аналитику. Это инструмент, который срезает самую нудную часть работы: переписывание требований человеческим языком, перебор сценариев, форматирование. Всё, что требует понимания контекста и ответственности за точность, остаётся за человеком.

Модель пишет черновик. Вы — редактируете, проверяете и подписываете. Так же, как с AI в системном анализе, где LLM помогает собирать требования, но не принимает за вас проектных решений. И точно так же, как при написании ТЗ для разработчика — шаблон и структуру даёт инструмент, а смысл и точность обеспечиваете вы.

И да, если коллеги спросят, почему документация стала появляться быстрее, — можете честно сказать, что вам помогает AI. Или загадочно улыбнуться. Выбор за вами.