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

Даниэле Прочида
Технический директор, Canonical
Документация — это не просто технические тексты и не процесс их написания. Она формирует отношение пользователя к продукту. Документация также влияет на то, как сами создатели видят свой продукт. Все, кто связан с продуктом, должны думать об этом.
Алисса Рок
Комьюнити-менеджер, The Good Docs Project
Очевидно, что разработчики ценят хорошую документацию, ведь они прекрасно знают, насколько сложно бывает пользоваться инструментом, документация к которому оставляет желать лучшего. Просто им не всегда удается разобраться, как делать действительно хорошую документацию.
Крис Чинчилья
Писатель и подкастер, chrischinchilla.com
В нашем писательском сообществе ведутся бесконечные споры о языке, инструментах и методиках. Однако цифры показывают, что нам нужны инструменты, обучающие программы и рекомендации, которые сделают процесс написания качественной документации более простым для каждого.
Внутренняя документация
Документация по коду
Документация для клиентов
Другое
Большинство респондентов пишут внутреннюю документацию и документацию к коду. Доля тех, кто работает над материалами, предназначенными для клиентов, за год снизилась на четыре процентных пункта.
Инструменты для написания документации
Авторы документации все еще предпочитают настраиваемые текстовые редакторы. Это простой, гибкий и эффективный способ редактирования текста и кода, который отлично подходит для написания документации.
Однако в этом году доля пользователей таких редакторов сократилась на семь процентных пунктов, в то время как доля GitHub Pages увеличилась на шесть. При этом Confluence, популярный инструмент для совместного создания вики-документации, сохраняет свои позиции.
46%
39%
Настраиваемый текстовый редактор
49%
32%
Confluence или другая wiki-платформа
28%
30%
Офисное приложение
24%
23%
Google Docs
Из 3% респондентов, использующих профессиональные инструменты для написания документации, 42% предпочитают собственные решения. Среди других инструментов выделяется новый вариант Paligo с долей 5%. Остальные популярные варианты — это хорошо известные традиционные инструменты.
Больше половины тех, кто пишет технические тексты, не думали о том, чтобы попробовать профессиональный инструмент, но 45% готовы рассмотреть такую возможность.
Разметка
Самым популярным форматом по-прежнему остается Markdown. Однако, по сравнению с прошлым годом, и стандартный Markdown, и его разновидности несколько сдали свои позиции, потеряв 7 и 4 процентных пункта соответственно. В то же время приложения с визуальным редактором и Office-подобные приложения стали популярнее на 6 процентных пунктов. Значит ли это, что удобство и простота использования становятся важнее контроля над исходными данными?
77%
70%
Markdown
18%
24%
Не знаю / использую WYSIWYG-редактор или офисное приложение
13%
9%
Пользовательский вариант Markdown
5%
6%
XML/DITA/DocBook и т. п.
5%
5%
AsciiDoc
4%
4%
reStructuredText
4%
3%
Другое
Повторное использование контента и шаблоны
Почти половина опрошенных использует структурированный подход к повторному использованию контента, но 32% все еще копируют материалы вручную, возможно, из-за ограничений инструментов, что может привести к несоответствиям и замедлить документирование.
Да, я храню контент в виде сниппетов и делаю ссылки на них из разных документов
Нет, мои инструменты не поддерживают повторное использование контента, поэтому я просто копирую повторяющийся контент
Нет, у меня нет необходимости использовать контент повторно
Различные типы тем и документов
Повторяющийся контент, например указания и предупреждения
Сложные элементы разметки
Автоматизированные проверки и качество документации
Только 13% респондентов пользуются автоматизированными проверками технической документации. Подавляющее большинство опрошенных пишут тесты своими силами, а не используют общедоступные линтеры, скорее всего, потому что эти тесты направлены на выявление ошибок в разметке и ссылках. Для проверки орфографии и грамматики предпочтение отдается встроенным спеллчекерам.
Да, в моем редакторе есть встроенная проверка орфографии и/или грамматики
Нет, мы полагаемся на редактуру
Использую внешний сервис
У нас есть автоматические проверки правописания
Документация по API
Больше половины опрошенных пишут API-документацию. Чаще других это делают разработчики (81%). За ними следуют архитекторы (19%), технические писатели (18%) и DevOps-инженеры (17%). Другие сотрудники в меньшей степени вовлечены в эту работу, а среди высших руководителей на позициях CIO, CEO и CTO этим занимаются лишь 7%.
81%
68%
Разработчик/программист
19%
11%
Архитектор
18%
14%
Технический писатель
17%
13%
DevOps-инженер / разработчик инфраструктуры
61%
Большинство опрошенных автоматически генерируют API-документацию из кода, что говорит об эффективности их процессов документирования. Что касается инструментов, то здесь доминирует Swagger с долей 84%.
Swagger
ReDoc
Другое
2/3
Примерно две трети тех, кто использует автоматизацию, все равно вынуждены вручную дополнять сгенерированный контент. Автоматизация ускоряет базовые задачи, но для формирования контекста и персонализации материалов важен человеческий вклад.
Языки и локализация
Основным языком технической документации по-прежнему остается английский. За ним с большим отставанием идет китайский, потерявший в этом году четыре процентных пункта. На третьем месте японский язык — его доля с прошлого года выросла на семь процентных пунктов.
На другие языки документацию переводят только 14% респондентов, а 8% рассматривают такую возможность. По сравнению с прошлым годом здесь нет существенных изменений.
Спасибо, что уделили время!
Если результаты исследования показались вам интересными, поделитесь ими с друзьями и коллегами.
Если у вас есть вопросы или пожелания, свяжитесь с нами по адресу surveys@jetbrains.com.