Сижу ночью, дописываю API-референс. Седьмой час за этим делом. Описание эндпоинта /users/{id}/orders — и я уже три абзаца объясняю, что возвращает JSON с юзером и его заказами, хотя любой разработчик откроет пример ответа и всё поймёт за 10 секунд. Проблема не в том, что мне лень. Проблема в том, что документация — это отдельный жанр, и ему нужно учиться. А времени на это нет.
Потом я попробовал написать часть доки с помощью Claude. Не всю, не как замену — просто кусок. И оказалось, что для технической документации он подходит неплохо, но есть нюансы. Делюсь тем, что понял за несколько месяцев.
Зачем вообще заморачиваться
Техническая документация — странная штука. Ты пишешь её для людей, которые не знают, что у тебя внутри, и которым нужно быстро решить задачу. Хорошая доку — это не «всё, что я знаю о системе». Это ответы на конкретные вопросы. А хороший ИИ-ассистент как раз умеет работать с запросами, а не с объёмом.
Но вот что я понял: просто попросить «напиши документацию к нашему API» — почти бесполезно. Получишь общие фразы. Смысл в том, чтобы дать Claude контекст и структуру, а потом работать с результатом как с черновиком.
Что Claude делает хорошо
Первое — генерирует шаблоны. Даёшь ему кусок кода или описание фичи, а он выдаёт структуру: параметры, типы, формат ответа, коды ошибок. Для этого не нужно быть писателем — нужно просто скормить ему схему.
Второе — переводит с человеческого на человеческий. Бывает, разработчик объясняет что-то устно, и ты понимаешь, но записать это нормально не можешь. Говоришь Клоду: «Вот что сказал разработчик, запиши это как docstring». И он берёт словарный беспорядок и превращает в читаемый текст.
Третье — держит стиль. Если есть примеры других страниц той же документации, можно сказать: «Пиши в таком стиле» — и он примерно следует. Не идеально, но экономит правки.
Как я это делаю на практике
Не одной командой «напиши всю документацию». Разбиваю на этапы.
Сначала — схема. Беру свой код, swagger-спеку или просто заметки из чата с разработчиком, и прошу: «Составь список того, что нужно задокументировать по этому эндпоинту». Обычно он находит вещи, которые я забыл упомянуть: валидацию, edge cases, rate limits.
Потом — черновик по секциям. Для каждого эндпоинта прошу: «Напиши описание, параметры, тело запроса, формат ответа, коды ошибок». Одну секцию за раз. Смотрю, что получилось, правлю.
Потом — ревью. Здесь важно: нельзя просто скопипастить. Проверяю, нет ли в тексте «естественно», «безусловно», «таким образом» и прочего мусора, который выдаёт ИИ-текст. И перепроверяю технические детали. Клод иногда hallucinationит — подставляет коды ошибок, которых нет, или описывает параметр неправильно. Это не катастрофа, если знаешь предметную область.
Где он косячит
Клод уверенно пишет вещи, в которых не уверен. Это главная проблема. Ты просишь «опиши формат даты в ответе», он пишет RFC 3339. Звучит умно, но если у тебя на самом деле Unix timestamp — будет неловко. Поэтому любую конкретику перепроверяю по коду или спрашиваю у разработчика.
Второе — он любит подробности. Пишет длинные абзацы туда, где хватит одной строки. Для документации это минус. Люди приходят за ответом, а не за эссе. Приходится резать.
Третье — контекст. Без хорошего промпта он не знает, кто читатель. «Пиши для джунов» и «пиши для опытных разработчиков» — это разные тексты. Чем точнее опишешь аудиторию и уровень экспертизы, тем лучше результат.
Промпты, которые у меня заработали
Несколько шаблонов, которые использую постоянно.
Первый — для генерации секции: «Напиши документацию к REST-эндпоинту [метод] [путь]. Контекст: [что делает]. Аудитория: [кто читает]. Формат: описание, параметры, тело запроса, формат ответа, коды ошибок. Не больше трёх предложений в каждой секции».
Второй — для перевода: «У меня есть заметки от разработчика: [текст]. Переведи в формат технической документации, убери лишнее, сохрани точность».
Третий — для ревью: «Вот текущая документация: [текст]. Найди несоответствия, пропущенные параметры, стилистические ошибки».
Работает лучше, чем пытаться получить всё за один промпт.
Что в итоге
Я не экономлю 100% времени на документации. Может, процентов 40–50. Но главное — пропало отвращение. Раньше садился за доки и просто не мог заставить себя писать. Теперь сажусь, даю Клоду черновик, правлю, и за час получается то, на что раньше уходило полдня.
Документация — это не магия. Это структурированная информация. А структуру ИИ генерирует неплохо. Главное — не доверять ему слепо и не пытаться заменить им человеческое понимание продукта.
Если делаешь доки для своего проекта — попробуй. Не как замену, а как ускоритель. Разница между «я неделю не мог заставить себя сесть за документацию» и «я потратил два часа и получил черновик» — она существенна.
