Документация — это та штука, которую все признают важной и которую каждый откладывает до понедельника. У меня в прошлом году накопилось несколько статей про API, которые нужно было оформить нормально. Процесс знакомый: сел, начал писать — и через полчаса понял, что потратил 25 минут на поиск правильного форматирования и только 5 — на сам текст.
Потом попробовал делегировать часть работы Claude. Не всю — на это я пока не готов. Но отдельные куски: черновики описаний эндпоинтов, разборы edge cases, даже первый набросок инструкции по запуску.
Результат удивил. Не идеал, но сокращает время на рутину заметно.
Отдаю контекст — получаю черновик
Самый рабочий сценарий: есть схема эндпоинта, нужно описание. Раньше я копировал JSON, писал рядом пояснение — и так для каждого поля. Скучно, механически.
Теперь кидаю Клоду схему с парой строк контекста:
Вот эндпоинт POST /subscriptions — создание подписки.
Схема в JSON Schema (прикреплю ниже). Напиши документацию
в стиле нашего API: кратко, с примерами запроса и ответа.
Клод выдаёт текст с описанием каждого поля, примерами, кодами ошибок. Первая версия почти всегда требует правки — но это уже дошлифовка, а не создание с нуля.
Замечание: сразу предупреждаю, что первая версия бывает слишком общей. Клод понимает задачу, но не знает нюансов — какие поля реально вызывают вопросы, какие edge cases задокументировать обязательно, какие сокращения я использую в команде. Поэтому работаю итеративно: сначала минимальный промпт, потом дополняю контекстом.
Как сформулировать промпт — два приёма, которые реально работают
Первый приём — дать образец. Один пример из предыдущей документации, даже кривой, работает лучше, чем абзац объяснений. Клод улавливает паттерн точнее, чем следует инструкциям.
Второй — рассказать, кто будет читать. Не «документация для разработчиков», а «новый разработчик, который первый день на проекте, должен по этому тексту запустить интеграцию». Разница огромная. С первым вариантом Клод пишет формально и правильно. Со вторым — пытается быть полезным.
Третий приём: описать формат явно. «В формате markdown, таблица с полями, пример curl-запроса, код ошибки и расшифровка». Без этого Клод выбирает формат сам — и не всегда тот, который удобен.
Улучшаю текст, а не пишу с нуля
С текстом, который написал я сам, Клод работает точнее, чем с пустого листа. Беру свой черновик — сленговый, кривой, местами недописанный — и прошу причесать:
«Сделай текст менее разговорным, но сохрани конкретику. Убери вводные обороты, которые добавляют слова, но не смысл. Не пиши «следует отметить», «важно подчеркнуть», «необходимо учитывать» — эти фразы здесь лишние.»
И вот что странно: результат всё равно иногда выглядит «слишком правильным». Текст ровный, грамотный — и мёртвый. Как будто его писал кто-то, кто очень хотел хорошо написать.
Справляюсь так: добавляю «пиши как разработчик пишет в чат коллеге, а не как в учебнике». Работает лучше, чем длинные инструкции по стилю.
Разбираюсь в сложном процессе — Клод ловит пропуски
Самый интересный сценарий — когда я сам до конца не понимаю, как процесс устроен. Берёшь описание от PM, кусок кода, логи — и кидаешь всё в чат с вопросом: «Объясни, что здесь происходит, и найди, где описание не совпадает с реализацией».
Клод в таком режиме работает как первый читатель, который задаёт неудобные вопросы. Не потому что умный — а потому что не знает контекста и честно сообщает, где логика хромает. Это иногда полезнее, чем спрашивать коллегу, который уже врос в проект и не замечает очевидного.
Ещё один приём: прошу описать процесс своими словами. Без документа, просто словами. Обычно на третьем предложении становится видно, где я сам плаваю — и это самое ценное.
Что в итоге
Claude не заменяет технического писателя. Он заменяет ту часть работы, где ты сидишь и перекладываешь слова. Берёт на себя черновики, форматирование, первичную структуру. Фактический материал, контекст продукта, понимание аудитории — это по-прежнему моё.
Главное, что изменилось: документация перестала быть подвигом. Раньше это был проект, к которому нужно было морально готовиться. Теперь — задача, которую можно начать и не чувствовать себя виноватым за качество черновика.
