ДалееСледующее руководство
How to Beat Writer's Block with AI
Приложения
РУКОВОДСТВО ПО ПРИМЕНЕНИЮ
ИИ для технических писателей означает использование языковых моделей для составления документации на основе спецификаций и кода, поддержание единообразия стиля и поддержку рабочих процессов «документы как код», при этом писатель остается ответственным за точность и структуру.
Прослушайте это руководствоОзвучено ИИ · ~3 min
Это важно, потому что документация часто отстает от быстро развивающихся продуктов. ИИ может ускорить разработку и обновление, но он также может изобретать параметры или поведение, которые звучат убедительно.
Техническое письмо уже давно частично автоматизировано. Справочная документация обычно создается на основе комментариев к коду или спецификаций API с помощью таких инструментов, как Swagger UI, Redoc и Sphinx autodoc. Генеративный ИИ добавляет прозу: концептуальные объяснения, учебные пособия, примеры, примечания к выпуску и первые черновики, написанные на основе документов с требованиями к продукту или технических заметок. Многие команды работают по модели «документы как код». Документация существует в виде Markdown или reStructuredText в Git, изменения вносятся через запросы на включение, а непрерывная интеграция создает сайт с помощью генератора статических сайтов, такого как Docusaurus, MkDocs или Sphinx. Эта установка хорошо подходит для ИИ. Черновики поступают в виде проверяемых изменений, автоматические проверки выполняются при каждом коммите, а обновления документации могут быть привязаны к вызвавшим их изменениям кода. Для обеспечения единообразия стиля детерминированные инструменты и ИИ дополняют друг друга. Линтер, такой как Vale, применяет правила из руководства по стилю, например руководства по стилю документации для разработчиков Google или руководства по стилю письма Microsoft, и каждый раз дает один и тот же результат. ИИ лучше предлагает более четкие формулировки, но он менее предсказуем. Главный риск – уверенная неточность. Модель может придумать конечную точку, значение по умолчанию или флаг командной строки, который выглядит правдоподобно. Он также может описывать, как продукт вел себя в обучающих данных, а не как он ведет себя сейчас. Каждый сгенерированный образец кода и параметр необходимо сверить с реальной системой. Распространенное заблуждение заключается в том, что ИИ делает технических писателей ненужными. Сложными частями работы являются знание того, что является правдой, принятие решения о том, что нужно пользователям, и организация информации, чтобы они могли ее найти. Такие структуры, как Diátaxis, в которых разделены учебные пособия, практические руководства, ссылки и объяснения, отражают эту структурную работу. Роли смещаются в сторону информационной архитектуры, проверки, контентной стратегии и написания для читателей, использующих ИИ. Например, предложение llms.txt от 2024 года предполагает файл, который указывает языковые модели на ключевую документацию сайта.
Автор предоставляет ИИ спецификацию OpenAPI и шаблон страницы команды и просит концептуальный обзор и руководство по началу работы. Затем они запускают каждый образец кода в тестовой среде.
Репозиторий документации запускает прозаический линтер Vale в непрерывной интеграции для пометки запрещенных терминов и пассивного залога. Помощник ИИ предлагает переписать помеченные предложения, а автор принимает или отклоняет каждое из них.
Когда запрос на включение инженера переименовывает флаг конфигурации, этап ИИ составляет соответствующее изменение документации. Автор просматривает его перед объединением.
Автор реструктурирует длинную страницу устранения неполадок в отдельные разделы с описательными заголовками. Это помогает читателям и помощникам искусственного интеллекта, извлекающим отрывки из документов.
Документация, вероятно, будет создаваться и обновляться более непрерывно, наряду с изменениями кода, при разработке ИИ и одобрении людей. Все больше читателей будут получать доступ к документам через помощников искусственного интеллекта, а не просматривать их, что повышает ценность точного, хорошо структурированного контента, который работает при чтении по частям. Такие соглашения, как llms.txt, все еще являются предложениями, и их принятие остается под вопросом. Спрос на чистое черчение может упасть, тогда как спрос на людей, умеющих проверять техническую точность, проектировать информационную архитектуру и качество собственной документации, может оставаться стабильным или расти. Как расколется рынок труда, пока неясно.
Бесплатная рассылка
Три проверенных AI-истории каждое утро буднего дня, написанные простым английским. Бесплатно навсегда, без рекламы.
Одно электронное письмо каждый будний день. Отписаться в один клик. Мы никогда не продаем и не передаем ваш адрес.
Проверьте себя
Мгновенная обратная связь по каждому ответу и общий сертификат с проверяемым идентификатором после прохождения курса.
Поддержите бесплатное образование в области искусственного интеллекта. AI Understanding — это некоммерческая организация 501(c)(3). Никакой рекламы и платного доступа. Сделать пожертвование
ИИ для технических писателей означает использование языковых моделей для составления документации на основе спецификаций и кода, поддержание единообразия стиля и поддержку рабочих процессов «документы как код», при этом писатель остается ответственным за точность и структуру. Это важно, потому что документация часто отстает от быстро развивающихся продуктов. ИИ может ускорить разработку и обновление, но он также может изобретать параметры или поведение, которые звучат убедительно.
Vale — это прозаический линтер, который детерминированно обеспечивает соблюдение правил стиля. Предложения ИИ по более четкой формулировке менее предсказуемы.
В формате «документы как код» документы хранятся в Git в формате Markdown или аналогичном, проходят через запросы на включение и создаются с помощью CI с помощью генераторов статических сайтов.
Diátaxis разделяет документацию на учебные пособия, практические руководства, ссылки и пояснения, каждое из которых отвечает различным потребностям пользователя.
Уверенная неточность – главный риск. Исполняемые образцы приводят к сбою сборки изобретенного параметра.
llms.txt, предложенный в 2024 году, представляет собой соглашение, позволяющее направлять языковые модели в важные документы. Его принятие все еще остается под вопросом.
Продолжайте учиться
Другие руководства, выбранные по этой теме
ДалееСледующее руководство
How to Beat Writer's Block with AI
Приложения