Техническое писательство

Поделиться:

Вопросы из этого раздела мы задавали только тем, кто занимается написанием технической документации.

12% всех участников нашего опроса сообщили, что так или иначе занимаются написанием технической документации. Но только 10% из них официально занимают должность технического писателя.

То есть 90% тех, кто пишет документацию, не считают себя техническими писателями. На основании этого возникают вопросы о межкомандном взаимодействии, о качестве и единообразии документации и о роли технических писателей.

Даниэле Прочида

Технический директор, Canonical

Документация — это не просто технические тексты и не процесс их написания. Она формирует отношение пользователя к продукту. Документация также влияет на то, как сами создатели видят свой продукт. Все, кто связан с продуктом, должны думать об этом.

Алисса Рок

Комьюнити-менеджер, The Good Docs Project

Очевидно, что разработчики ценят хорошую документацию, ведь они прекрасно знают, насколько сложно бывает пользоваться инструментом, документация к которому оставляет желать лучшего. Просто им не всегда удается разобраться, как делать действительно хорошую документацию.

Крис Чинчилья

Писатель и подкастер, chrischinchilla.com

В нашем писательском сообществе ведутся бесконечные споры о языке, инструментах и методиках. Однако цифры показывают, что нам нужны инструменты, обучающие программы и рекомендации, которые сделают процесс написания качественной документации более простым для каждого.

Какую документацию вы пишете?

Большинство респондентов пишут внутреннюю документацию и документацию к коду. Доля тех, кто работает над материалами, предназначенными для клиентов, за год снизилась на четыре процентных пункта.

Инструменты для написания документации

Авторы документации все еще предпочитают настраиваемые текстовые редакторы. Это простой, гибкий и эффективный способ редактирования текста и кода, который отлично подходит для написания документации.

Однако в этом году доля пользователей таких редакторов сократилась на семь процентных пунктов, в то время как доля GitHub Pages увеличилась на шесть. При этом Confluence, популярный инструмент для совместного создания вики-документации, сохраняет свои позиции.

Какие инструменты вы используете для создания документации?

Какое профессиональное решение для создания документации вы используете?

Из 3% респондентов, использующих профессиональные инструменты для написания документации, 42% предпочитают собственные решения. Среди других инструментов выделяется новый вариант Paligo с долей 5%. Остальные популярные варианты — это хорошо известные традиционные инструменты.

Довольны ли вы используемым инструментом?

Интересно, что целых 30% тех, кто использует специальные инструменты для написания документации, ищут варианты получше.

Рассматривали ли вы возможность использования специального инструмента для написания технической документации?

Больше половины тех, кто пишет технические тексты, не думали о том, чтобы попробовать профессиональный инструмент, но 45% готовы рассмотреть такую возможность.

Разметка

Самым популярным форматом по-прежнему остается Markdown. Однако, по сравнению с прошлым годом, и стандартный Markdown, и его разновидности несколько сдали свои позиции, потеряв 7 и 4 процентных пункта соответственно. В то же время приложения с визуальным редактором и Office-подобные приложения стали популярнее на 6 процентных пунктов. Значит ли это, что удобство и простота использования становятся важнее контроля над исходными данными?

Поделиться мнением

Какой язык разметки вы используете для создания технической документации?

Повторное использование контента и шаблоны

Почти половина опрошенных использует структурированный подход к повторному использованию контента, но 32% все еще копируют материалы вручную, возможно, из-за ограничений инструментов, что может привести к несоответствиям и замедлить документирование.

Используете ли вы созданный контент повторно при написании документов или руководств?

Используете ли вы шаблоны, чтобы ускорить процесс написания текстов?

Для каких объектов вы настраиваете шаблоны?

Создаете ли вы параметризованные шаблоны (например, содержащие переменные)?

69% опрошенных не используют шаблоны для ускорения работы, но большинство тех, кто все же пользуется ими, применяют их для разных типов документов. Что касается динамических шаблонов с переменными, то здесь мнения разделились почти поровну.

Автоматизированные проверки и качество документации

Только 13% респондентов пользуются автоматизированными проверками технической документации. Подавляющее большинство опрошенных пишут тесты своими силами, а не используют общедоступные линтеры, скорее всего, потому что эти тесты направлены на выявление ошибок в разметке и ссылках. Для проверки орфографии и грамматики предпочтение отдается встроенным спеллчекерам.

Вы пользуетесь автоматизированными проверками технической документации?

Какие проверки у вас есть?

Автоматизирована ли у вас проверка орфографии, грамматики и стиля текстов?

Документация по API

Больше половины опрошенных пишут API-документацию. Чаще других это делают разработчики (81%). За ними следуют архитекторы (19%), технические писатели (18%) и DevOps-инженеры (17%). Другие сотрудники в меньшей степени вовлечены в эту работу, а среди высших руководителей на позициях CIO, CEO и CTO этим занимаются лишь 7%.

Пишете ли вы API-документацию?

Написание API-документации в зависимости от должности

Генерируете ли вы автоматически API-документацию из кода?

61%

Большинство опрошенных автоматически генерируют API-документацию из кода, что говорит об эффективности их процессов документирования. Что касается инструментов, то здесь доминирует Swagger с долей 84%.

Какие инструменты вы используете?

Вам приходится вручную дополнять автоматически сгенерированную API-документацию?

2/3

Примерно две трети тех, кто использует автоматизацию, все равно вынуждены вручную дополнять сгенерированный контент. Автоматизация ускоряет базовые задачи, но для формирования контекста и персонализации материалов важен человеческий вклад.

Языки и локализация

Основным языком технической документации по-прежнему остается английский. За ним с большим отставанием идет китайский, потерявший в этом году четыре процентных пункта. На третьем месте японский язык — его доля с прошлого года выросла на семь процентных пунктов.

На каком языке вы в основном пишете документацию?

Переводите ли вы документацию на другие языки?

На другие языки документацию переводят только 14% респондентов, а 8% рассматривают такую возможность. По сравнению с прошлым годом здесь нет существенных изменений.

Техническое писательство:

2023

Спасибо, что уделили время!

Если результаты исследования показались вам интересными, поделитесь ими с друзьями и коллегами.

Если у вас есть вопросы или пожелания, свяжитесь с нами по адресу surveys@jetbrains.com.