Час убитый на то, чтобы объяснить джуну как работает наш API — и в итоге он всё равно переспрашивает. Знакомо? Я через это прошёл раз пять, прежде чем начал систематически писать доки. А потом попробовал делать это вместе с Claude — и кое-что поменялось.
Расскажу честно: не "Claude решил все мои проблемы с документацией". Скорее — где он реально помогает, где я обжёгся, и что пришлось перестроить в своём подходе.
Откуда берётся плохая документация
Раньше я думал, что плохие доки пишут ленивые разработчики. Оказалось — нет. Чаще всего проблема в другом: человек, который пишет документацию, слишком хорошо знает продукт. Он пропускает шаги, которые кажутся ему очевидными. Объясняет термины через другие термины. Пишет "просто вызовите метод authenticate()" — и не уточняет, что перед этим нужно инициализировать клиент, получить токен и проверить регион.
Claude в этом месте оказался полезен неожиданным способом. Я даю ему черновик и прошу сыграть роль человека, который видит этот API впервые. Он начинает задавать вопросы: "А что такое session_id в этом контексте?", "Ты написал что нужно передать флаг — какие значения он принимает?". Не магия, но работает как дополнительный читатель, у которого нет моего контекста.
Как я строю процесс
Пробовал разные подходы. Первый — давать Claude голый код и просить написать документацию. Результат был технически корректным, но мёртвым. Текст без понимания зачем это нужно пользователю, без примеров из реального использования, без предупреждений о граблях.
Дальше я попробовал иначе. Пишу черновик сам — пусть кривой, пусть неполный — и работаю с Claude как с редактором. Даю ему контекст: кто будет читать, какой у них уровень, что они пытаются сделать. И прошу найти дыры, непоследовательности, места где я перескакиваю через шаги.
Для API-документации у меня теперь такой порядок. Сначала описываю endpoint словами — что он делает, зачем, когда его используют. Потом прошу Claude на основе этого описания сгенерировать скелет: параметры, типы, возможные ошибки. А потом сам дописываю примеры из реальных кейсов — это Claude сделать не может, он не знает как клиенты реально используют продукт.
Где я потратил время впустую
Несколько недель я пытался автоматизировать генерацию доков из кода напрямую. Давал Claude функцию на Python — получал описание. Звучит удобно. На практике такие доки приходилось переписывать почти полностью: Claude описывает что делает код, а не зачем он существует и как его правильно использовать. Разница принципиальная.
Ещё один тупик — документация для внутренней системы без контекста. Claude генерировал вполне связный текст, абсолютно бесполезный, потому что не учитывал наши соглашения, наши термины, наши паттерны. Пришлось сначала написать короткий документ о том, что за продукт, кто им пользуется, какой у нас стиль. После этого качество выросло заметно. Этот документ я теперь даю Claude в начале каждой сессии.
Что реально работает
Лучший результат у меня выходит с туториалами — пошаговыми инструкциями типа "сделай X с нуля". Моя роль — дать структуру и реальные примеры. Роль Claude — сделать текст последовательным, добавить переходы между шагами, поймать места где я перепрыгнул через объяснение.
Хорошо работает вычитка на понятность. Я прошу Claude перефразировать абзац так, чтобы его понял разработчик без опыта в нашей предметной области. Иногда результат лучше моего, иногда хуже — но это всегда повод пересмотреть формулировку.
Ещё одна вещь, которую я теперь делаю регулярно — прошу Claude сгенерировать список вопросов, которые может задать читатель после прочтения раздела. Неплохо показывает дыры в объяснении.
Что Claude не умеет делать за тебя
Он не знает, что ваш метод падает при определённом размере payload — потому что это выяснили только после трёх обращений в поддержку. Не знает, что вот эту функцию лучше не использовать в продакшне, хотя она есть в API. Не знает контекст решений, которые принимались два года назад и теперь живут в кодовой базе как legacy.
Весь этот "тёмный контекст" — то, что живёт в головах у команды — нужно вытащить самому и дать Claude как исходник. Тогда он становится полезным. Без этого генерирует красивую ерунду.
Документация — это не про слова. Это про знание, которое нужно передать. Claude помогает с первым, но второе никуда не делось.
