Недавно в Москве прошла первая международная конференция для технических писателей – TechWriter Days. Это событие собрало и объединило специалистов, занимающихся технической документацией, предоставив возможность обсудить актуальные темы, тенденции и лучшие практики в этой области.
Если вы посетили эту конференцию, то уже знаете, что наша компания «Документерра» приняла в ней участие. Мы были не только серебряным партнером мероприятия, но и наш технический директор выступил с докладом о мировых трендах в сфере технической документации. Хотя формат выступления не позволил охватить всю интересную статистику, собранную нами, мы не могли упустить возможность поделиться с вами всей этой ценной информацией. Подробнее об этом в нашем блоге.
Искусственный интеллект и технические писатели
Технические писатели столкнулись с растущим влиянием искусственного интеллекта на их профессию. Что вызвало вопросы о будущем технической коммуникации и роли специалистов в этой области. Том Джонсон провел опрос среди техписов из США, Индии, Канады и Западной Европы, чтобы выяснить, чего они ожидают. Его результаты представлены ниже.
1. Степень обеспокоенности относительно будущего профессии техписа из-за способности искусственного интеллекта упрощать сложный контент следующая:
степень обеспокоенности техписов относительно своей профессии в будущем
Остальные опрошенные не беспокоятся совсем.
Это показывает большую озабоченность среди технических писателей и обосновывает их фокус на этой теме.
2. К какой профессии они скорее всего перейдут, если роль технического писателя исчезнет в будущем?
Среди топ ответов были следующие:
рассматриваемые техписами профессии в качестве запасных
Все логично, ведь многие техписы уже занимаются такими аспектами как стратегия контента и архитектуры информации.
3. Принимая во внимание, что создание текстов — лишь часть работы технического писателя, насколько вероятно, что инструменты искусственного интеллекта изменят техническую коммуникацию радикально?
вероятность изменения техкомм благодаря ИИ
Чуть меньше половины опрошенных (42%) считают, что это вероятно и 23% дают очень высокую вероятность такого сценария, остальные сомневаются, что это возможно. Большинство техписов считает, что искусственный интеллект способствует трансформации технической коммуникации. То есть ИИ повлияет не только на способность писать документацию, но и другие аспекты работы техписа.
4. Учитывая, что ИИ достаточно хорошо читает, объясняет и создает код, сильнее ли это повлияет на работу разработчиков с доками по сравнению с работой, где преобладает творчество?
Большинство респондентов считают, что самые значительные трансформации в технической коммуникации произойдут в API документации. В результате фокус может сместиться на более концептуальные документы, которые создаются человеком. Кто-то должен будет следить за тем, чтобы документация соответствовала стандартам, так что, возможно, значение хорошей документации повысит роль технического писателя.
5. Произойдет ли в скором времени спад интереса к теме ИИ?
Здесь мнения разделились практически поровну среди тех, кто считает, что скоро интерес к ИИ угаснет и тех, кто думает, что такое вряд ли произойдет.
6. Учитывая быстрое развитие ИИ, сможет ли он через год (т.е. в 2025 году) сам писать всю документацию, которую сейчас пишут техписы?
Несмотря на то, что 25% опрошенных считают, что уже через год ИИ сможет сам писать документацию, используя вводные данные, есть ряд причин, которые этому препятствуют:
- отсутствие документации, на которую можно опираться,
- отсутствие контекста (обсуждения, письма, презентации,баг-отчеты и т.п.),
- комментарии от других членов команды в процессе создания документации,
- ограничения на количество допустимых символов.
Все эти факторы указывают на то, что хотя искусственный интеллект может играть важную роль в автоматизации процессов создания документации, полностью автоматическое создание качественной документации вряд ли возможно в ближайшем будущем.
7. Будут ли существующие инструменты для документации включать больше функций, управляемых искусственным интеллектом?
94% респондентов подтверждают такую вероятность. Более многообещающими здесь выглядят облачные инструменты создания контента. Они более современные и их легче интегрировать с ИИ инструментами.
8. Станет ли навык письма менее ценным из-за способности ИИ писать тексты?
Ответы разделились:
вероятность обесценивания навыков письма
Несмотря на возможные преимущества использования искусственного интеллекта для написания текстов, большинство людей считает, что навык письма останется ценным и востребованным.
Люди обладают способностью анализировать контекст, понимать нюансы и принимать решения на основе широкого спектра факторов, что делает их незаменимыми при оценке качества и достоверности текстов.
Кроме того, человеческий фактор имеет значение в создании текстов, которые требуют творческого подхода, эмоциональной окраски или индивидуального стиля. Искусственный интеллект может быть ограничен в создании текстов с уникальным характером и личным оттенком, что делает человеческое вмешательство необходимым для поддержания индивидуальности и аутентичности текстов.
Поэтому, хотя использование ИИ может изменить способы написания текстов, навык письма останется важным и ценным, и люди всегда будут нужны хотя бы для проверки написанного.
Искусственный интеллект в документации
Существуют причины, по которым компании рассматривают возможность внедрения ИИ в свою документацию.
- В основном, это – ожидания клиентов, которые хотят получить такой же уровень сервиса, какой существует в потребительской сфере. С возросшим ожиданием пользователями быстрых, точных и персонализированных ответов, компании осознают, что использование искусственного интеллекта может помочь им удовлетворить эти потребности.
- Внутренние факторы эффективности.
Существует также доказательство того, что компании, внедрившие ИИ в свою документацию, видят снижение количества обращений в службу поддержки.
Zoomin Software изучили возможности интеграции искусственного интеллекта в процессы документирования и управления контентом. Вот несколько примеров:
- Объединение всей информации в одной системе, особенно при работе нескольких команд, использующих разные инструменты и форматы.
- Интеграция ИИ не только с помощью чат-ботов на основе GPT, но также таких функций как краткое изложение контента, считывание кода и работа с редакторами.
- Создание пользовательского опыта, адаптированного к конкретным потребностям аудитории, вместо применения универсального подхода.
Интеграция искусственного интеллекта в процессы документирования и управления контентом видится эффективной стратегией. Важным аспектом здесь является измерение успешности интеграции ИИ в платформу, что позволит компаниям оценить эффективность принятых мер и при необходимости внести коррективы в его работу.
Документация и API
Согласно ежегодному исследованию от Postman, 2023 State of the API Report
главной проблемой для использования API является документация, а именно ее нехватка или отсутствие, также среди основных причин назвали сложность обнаружения API (32%) и нехватку времени (27%).
API документация играет критическую роль в обеспечении успешного использования API разработчиками. Она предоставляет подробное описание функций, методов, параметров и примеров использования API, что позволяет разработчикам понять, как взаимодействовать с API и какие возможности оно предоставляет. Без достаточной или отсутствующей документации разработчики могут столкнуться с большими трудностями при понимании работы API и его интеграции в свои приложения.
В случае отсутствия документации разработчики вынуждены тратить дополнительное время на анализ и эксперименты с API, чтобы понять его функциональность и использование, что может привести к задержкам в разработке и повышению риска ошибок. Кроме того, сложность обнаружения API, как упоминается в отчете, указывает на то, что без четкой и доступной документации разработчикам сложно находить нужное API, что также замедляет процесс разработки.
Таким образом, документация API необходима для облегчения процесса разработки, ускорения интеграции и снижения риска ошибок, что делает ее отсутствие или нехватку основной проблемой для использования API.
Кто пишет API доки?
Jetbrains также проводили опрос о состоянии технической документации в среде разработчиков. Вот, что интересного удалось узнать об API доках:
- Более половины опрошенных пишут API-справки, причем разработчики (81%) больше всех вовлечены в подобные задачи.
- В меньшей степени написанием API-справок занимаются архитекторы (19%), технические писатели (18%) и DevOps инженеры (17%).
- Руководители разного уровня тоже пишут API-справки, но таких всего 7(%). Сюда входят и прочие роли.
- 61% опрошенных автоматически генерируют API-справки непосредственно из кода. Это говорит о том, что компании или разработчики придерживаются эффективных методов документирования. Что позволяет сэкономить время и ресурсы, автоматизируя процесс создания и обновления документации.
- Что касается инструментов, большинство респондентов (84%) предпочитают использовать Swagger для документирования своих API.
В индустрии разработки программного обеспечения многие прибегают к использованию инструментов автоматической генерации.
Техническая документация и разработчики
Что же еще интересного удалось узнать Jetbrains о технической документации?
- 12% опрошенных заявили, что они занимаются техписательством, но только 10% из них имеют должность технического писателя.
- Получается, что 90% тех, кто пишет документацию, не называют себя техническими писателями, что поднимает вопрос о необходимости командной работы.
Типы документации
Большинство респондентов работают над внутренней документацией (87%) и документацией на код (63%), а также пользовательской документацией (53%).
типы документов
Инструменты для создания технической документации
- Кастомизируемые текстовые редакторы по-прежнему являются самым популярным выбором для написания документации. Хотя интерес к ним снизился по сравнению с прошлым годом (39% против 46% ранее).
- В то же время наблюдается рост использования GitHub pages.
- Позиции Confluence, как основного wiki-инструмента для совместного документирования остались неизменны.
- Если же говорить о профессиональных инструментах для техписов — 42% предпочитают кастомные тулзы.
- Предпочтения остальных респондентов ожидаемо разделились среди популярных НАТ инструментов.
Markdown или WYSIWYG?
Происходят изменения в предпочитаемых форматах для написания технической документации:
- В то время как Markdown остается популярным выбором, наблюдается заметный переход от стандартного Markdown и его разновидностей к приложениям типа WYSIWYG и аналогам Microsoft Office.
Этот сдвиг может быть обусловлен тем, что пользователи ценят удобство использования и доступность интерфейса выше контроля над исходным кодом. Возможно, это связано с тем, что подобные приложения предоставляют более интуитивно понятный способ написания документации, особенно для тех, кто не имеет опыта работы с разметкой Markdown.
***
Техническая документация не теряет своей важности. Растет значимость интеграции искусственного интеллекта в процессы технической коммуникации. Эта интеграция рассматривается как эффективная стратегия. Для успешной работы с API также важна хорошо структурированная и полноценная API документация. При этом важно уделять внимание не только техническим аспектам, но и пользовательскому опыту.
Относительно инструментов для создания технической документации, мы видим желание пользователей иметь более удобный и интуитивно понятный интерфейс для создания документации.
В целом, исследования подчеркивают необходимость постоянного совершенствования процессов создания и управления технической документацией, включая адаптацию к новым технологиям и учет потребностей пользователей.
