ИИ для технических писателей

Техническое письмо уже давно частично автоматизировано. Справочная документация обычно создается на основе комментариев к коду или спецификаций API с помощью таких инструментов, как Swagger UI, Redoc и Sphinx autodoc. Генеративный ИИ добавляет прозу: концептуальные объяснения, учебные пособия, примеры, примечания к выпуску и первые черновики, написанные на основе документов с требованиями к продукту или технических заметок. Многие команды работают по модели «документы как код». Документация существует в виде Markdown или reStructuredText в Git, изменения вносятся через запросы на включение, а непрерывная интеграция создает сайт с помощью генератора статических сайтов, такого как Docusaurus, MkDocs или Sphinx. Эта установка хорошо подходит для ИИ. Черновики поступают в виде проверяемых изменений, автоматические проверки выполняются при каждом коммите, а обновления документации могут быть привязаны к вызвавшим их изменениям кода. Для обеспечения единообразия стиля детерминированные инструменты и ИИ дополняют друг друга. Линтер, такой как Vale, применяет правила из руководства по стилю, например руководства по стилю документации для разработчиков Google или руководства по стилю письма Microsoft, и каждый раз дает один и тот же результат. ИИ лучше предлагает более четкие формулировки, но он менее предсказуем. Главный риск – уверенная неточность. Модель может придумать конечную точку, значение по умолчанию или флаг командной строки, который выглядит правдоподобно. Он также может описывать, как продукт вел себя в обучающих данных, а не как он ведет себя сейчас. Каждый сгенерированный образец кода и параметр необходимо сверить с реальной системой. Распространенное заблуждение заключается в том, что ИИ делает технических писателей ненужными. Сложными частями работы являются знание того, что является правдой, принятие решения о том, что нужно пользователям, и организация информации, чтобы они могли ее найти. Такие структуры, как Diátaxis, в которых разделены учебные пособия, практические руководства, ссылки и объяснения, отражают эту структурную работу. Роли смещаются в сторону информационной архитектуры, проверки, контентной стратегии и написания для читателей, использующих ИИ. Например, предложение llms.txt от 2024 года предполагает файл, который указывает языковые модели на ключевую документацию сайта.