Сижу перед пустым файлом. README.md. Курсор мигает. Написать бы: «Это библиотека для работы с API», — но внутри шепчет голос: «Ты ж инженер, напиши как инженер, а не как студент на информатике». И вот уже полчаса я переписываю одно и то же предложение.
Знакомо? Мне — да. И это одна из причин, почему я вообще начал экспериментировать с языковыми моделями для документирования. Не чтобы они писали за меня, а чтобы вытаскивали из тупика.
Что я понял про документацию и почему её не пишут
Документацию не пишут не от лени. Её не пишут, потому что момент между «сделал фичу» и «надо её описать» — самый неудобный. Ты ещё в коде, ты ещё видишь все нюансы, но слова не идут. Хочется просто вернуться к коду.
Классический совет — docs as code, пиши одновременно с кодом. Звучит логично, на практике превращается в «напишу потом», а потом — через месяц, когда уже не помнишь, зачем там этот параметр.
Клод в эту картину встраивается не как замена автору, а как старший редактор, который сидит рядом и говорит: «Стоп, ты имеешь в виду вот это? Потому что то, что ты написал, читается иначе».
Как я работаю с Клодом для документации
Первый подход — дать контекст, а не задание. Самая частая ошибка: писать «напиши документацию для моей библиотеки». Клод выдаёт красивый, но абстрактный текст, который не отражает реальность.
Я делаю иначе. Даю код. Даю примеры использования. Даю проблему, которую библиотека решает. Даже даю текст, который уже написал — пусть кривой, пусть с ошибками — чтобы было от чего оттолкнуться.
Пример промпта, который у меня работает:
Вот функция
parse_config(path, validate=True, encoding='utf-8'). Она загружает JSON-конфиг по пути path. validate по умолчанию True, валидирует по схеме. Если файл не найден — кидает FileNotFoundError, если JSON битый — JSONDecodeError. Напиши раздел документации: что принимает, что возвращает, когда может упасть.
Конкретный кусок — конкретный ответ. Ни воды, ни общих фраз про «гибкость и надёжность».
Второй подход — итеративная дошлифовка. Первый результат — это черновик. Я читаю, нахожу места, где описание не совпадает с тем, что функция реально делает, и правлю. Или прошу Клода: «Здесь ты написал размыто, а мне нужно чтобы читатель понял: если validate=True и файла нет — программа упадёт. Сделай это явным».
Обычно уходит три-пять итераций. Это не минус — это нормальный редакторский процесс, просто быстрее.
Третий подход — проверка готового текста. Беру свой черновик и прошу: «Прочитай это от имени разработчика, который впервые видит наш проект. Скажи, что непонятно, что вызывает вопросы, что выглядит пустым». Иногда результат обескураживает — места, которые я считал очевидными, оказываются непонятными. Хорошо, что об этом узнал я, а не пользователь.
Где Клод реально помогает, а где нет
Помогает в трёх вещах.
Структурирование. Дали кусок кода — он предлагает логичную структуру: описание, параметры, возвращаемое значение, примеры, исключения. Не всегда идеальную, но отправную точку. Не нужно с нуля придумывать, как это должно выглядеть.
Примеры кода. Пожалуй, сильнейшая сторона. Написать рабочий пример с edge cases и пояснениями — бывает муторно. Клод генерирует, я проверяю, правлю, запускаю. Две-три итерации и пример готов.
Английский. Большая часть моей документации — на английском, проекты опенсорсные. Клод переводит с русского и сразу адаптирует под английскую техническую прозу — не дословно, а так, как принято в документации. «Принимает строку» → «Accepts a string». Мелочь, но экономит время.
Не помогает в двух вещах, которые важно понимать.
Клод не знает ваш контекст. Он не был на встрече, где вы решали, что библиотека должна делать. Он не видел, как пользователи путались с прошлой версией API. Этот контекст нужно давать явно. Чем больше — тем лучше результат.
Клод галлюцинирует API. Не часто, но бывает. Уверенно описывает параметр, которого нет, или возвращаемый тип, который не совпадает с реальностью. Поэтому любой сгенерированный текст нужно сверять с кодом. Я однажды пропустил — и в документации висело описание параметра, которого в функции не было. Не криминал, но неприятно.
Что я делаю практически
Мой рабочий процесс сейчас выглядит так. Начинаю писать код — параллельно кидаю в чат короткие заметки: «вот эта функция делает X, потому что раньше Y ломалось». Клод накапливает контекст. Когда код готов, прошу: «На основе нашего разговора напиши черновик README». Получается документ, который отражает не только что делает код, но и почему он написан так, а не иначе.
Для внутренних документов — архитектурных решений, инструкций по запуску — подход похожий, но с одним дополнением: прошу проверить текст на противоречия. «В одном месте написано, что сервис запускается на порту 8080, в другом — на 3000. Где ошибка?» Клод находит, я проверяю.
Коротко
Я не считаю, что языковая модель заменит человека в документировании. Но она снимает главный барьер — пустую страницу. Даёт черновик, структуру, варианты формулировок. А автор остаётся ответственным за то, правда ли это описывает то, что делает код.
И вот это, по-моему, главное: Клод берёт на себя механику, человек остаётся за смыслом.
