Я долго скептически смотрел на идею доверить документацию языковой модели. Технические тексты — это не эссе: там важна точность, структура, и одна неверная фраза в описании API может стоить разработчику нескольких часов отладки. Но потом я попробовал, и оказалось всё сложнее, чем "работает" или "не работает".
Расскажу, как я это использую сейчас — без иллюзий и без евангелизма.
Где я реально экономлю время
Первое, что прижилось — черновики. Не финальный текст, а именно точка отталкивания.
Раньше я садился писать описание эндпоинта и первые десять минут тратил на то, чтобы вообще начать. Теперь скидываю Claude сигнатуру функции, пару комментариев из кода — и через 30 секунд у меня есть что-то пригодное. Потом редактирую. Редактировать чужой текст всегда быстрее, чем писать с нуля.
Дело в том, что у любого проекта есть страницы, которые писались в спешке три года назад и теперь нечитаемы. Я вставляю такой текст, прошу сделать его понятнее без потери смысла — и обычно получаю нормальную основу. Это второй сценарий, который у меня работает стабильно.
Третий — перевод. Английская версия русской доки или наоборот. Claude справляется на уровне хорошего технического переводчика: не идеально, но достаточно.
Где я обжёгся
Первый раз я доверился слишком сильно. Попросил написать полный раздел документации по библиотеке, которую сам плохо знал. Получил красивый структурированный текст — и только потом заметил, что несколько методов описаны неверно. Не выдуманы, а именно неверно интерпретированы. Это хуже, чем пустое место.
Правило, которое я для себя вывел: Claude не должен знать предмет вместо меня. Я должен знать, что описываю — тогда модель помогает с формой, а не с содержанием. Как только пытаюсь использовать её как источник технических знаний о незнакомой теме — жди беды.
Ещё одна ловушка — стиль. Если не задать очень конкретный тон, получишь документацию в духе "приятного использования нашего продукта". Корпоративный туман, который технари ненавидят. Я научился сразу писать в запросе что-то вроде: "пиши сухо, без приветственных фраз, аудитория — разработчики с опытом, никаких очевидных объяснений".
Как я строю запрос, чтобы получить что-то полезное
Плохой запрос: "Напиши документацию для функции авторизации".
Хороший выглядит так: даю сигнатуру функции, описываю что она делает, говорю кто будет читать, указываю стиль — Stripe Docs, Google Developers, конкретные примеры работают лучше абстрактных описаний. И говорю что должно быть на выходе: только описание параметров или полный раздел с примерами кода.
Контекст решает почти всё. Чем точнее описана задача, тем меньше времени на переделку.
На практике ещё полезно давать примеры из уже написанной документации проекта. Тогда Claude подстраивается под существующий стиль, а не изобретает свой. Для больших проектов это принципиально — консистентность там важна.
Что Claude делает лучше, чем я
Честно: структуру он выстраивает лучше. У меня есть привычка писать документацию в том порядке, в котором я думал о задаче, а не в котором её удобно читать. Claude, если попросить, разобьёт материал на логичные блоки: что это, зачем нужно, как использовать, что может пойти не так, примеры.
С примерами кода отдельная история. Прошу написать минимальный рабочий пример для каждого метода — получаю что-то разумное. Проверяю, правлю, но основа есть.
Ещё он хорошо находит дыры. Я даю текст и прошу сказать, что неясно или чего не хватает — с точки зрения разработчика, который видит эту документацию впервые. Как ревью от коллеги, только коллега доступен в любое время и не обижается на тупые вопросы.
Что у меня получилось в итоге
Сейчас процесс выглядит так: структуру и ключевые технические детали я пишу сам — это то, где нужна точность и знание предмета. Черновики разделов, примеры, переформулировки — с Claude. Финальное редактирование снова я, потому что живой взгляд всё равно нужен.
Это не "делегировать документацию ИИ". Скорее — убрать самую нудную часть работы: стартовое трение и рутинное форматирование. Оставить себе то, что требует реального понимания.
Время на документацию сократилось примерно вдвое. Качество не упало — скорее наоборот, потому что я перестал откладывать написание из-за отвращения к чистому листу.
