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