Техническое писательство
Поделиться:
Вопросы из этого раздела мы задавали только тем, кто занимается написанием технической документации.
12% всех участников нашего опроса сообщили, что так или иначе занимаются написанием технической документации. Но только 10% из них официально занимают должность технического писателя.
То есть 90% тех, кто пишет документацию, не считают себя техническими писателями. На основании этого возникают вопросы о межкомандном взаимодействии, о качестве и единообразии документации и о роли технических писателей.
Даниэле Прочида
Технический директор, Canonical
Документация — это не просто технические тексты и не процесс их написания. Она форми рует отношение пользователя к продукту. Документация также влияет на то, как сами создатели видят свой продукт. Все, кто связан с продуктом, должны думать об этом.
Алисса Рок
Комьюнити-менеджер, The Good Docs Project
Очевидно, что разработчики ценят хорошую документацию, ведь они прекрасно знают, насколько сложно бывает пользоваться инструментом, документация к которому оставляет желать лучшего. Просто им не всегда удается разобраться, как делать действительно хорошую документацию.
Крис Чинчилья
Писатель и подкастер, chrischinchilla.com
В нашем писательском сообществе ведутся бесконечные споры о языке, инструментах и методиках. Однако цифры показывают, что нам нужны инструменты, обучающие программы и рекомендации, которые сделают процесс написания качественной документации более простым для каждого.
Большинство респондентов пишут внутреннюю документацию и документацию к коду. Доля тех, кто рабо тает над материалами, предназначенными для клиентов, за год снизилась на четыре процентных пункта.
Инструменты для написания документации
Авторы документации все еще предпочитают настраиваемые текстовые редакторы. Это простой, гибкий и эффективный способ редактирования текста и кода, который отлично подходит для написания документации.
Однако в этом году доля пользователей таких редакторов сократилась на семь процентных пунктов, в то время как доля GitHub Pages увеличилась на шесть. При этом Confluence, популярный инструмент для совместного создания вики-документации, сохраняет свои позиции.
Из 3% респондентов, использующих профессиональные инструменты для написания документации, 42% предпочитают собственные решения. Среди других инструментов выделяется новый вариант Paligo с долей 5%. Остальные популярные варианты — это хорошо известные традиционные инструменты.
Больше половины тех, кто пишет технические тексты, не думали о том, чтобы попробовать профессиональный инструмент, но 45% готовы рассмотреть такую возможность.
Разметка
Самым поп улярным форматом по-прежнему остается Markdown. Однако, по сравнению с прошлым годом, и стандартный Markdown, и его разновидности несколько сдали свои позиции, потеряв 7 и 4 процентных пункта соответственно. В то же время приложения с визуальным редактором и Office-подобные приложения стали популярнее на 6 процентных пунктов. Значит ли это, что удобство и простота использования становятся важнее контроля над исходными данными?
Автоматизированные проверки и качество документации
Только 13% респондентов пользуются автоматизированными проверками технической документации. Подавляющее большинство опрошенных пишут тесты своими силами, а не используют общедоступные линтеры, скорее всего, потому что эти тесты направлены на выявление ошибок в разметке и ссылках. Для проверки орфографии и грамматики предпочтение отдается встроенным спеллчекерам.
Документация по API
Больше половины опрошенных пишут API-документацию. Чаще других это делают разработчики (81%). За ними следуют архитекторы (19%), технические писатели (18%) и DevOps-инженеры (17%). Другие сот рудники в меньшей степени вовлечены в эту работу, а среди высших руководителей на позициях CIO, CEO и CTO этим занимаются лишь 7%.
61%
Большинство опрошенных автоматически генерируют API-документацию из кода, что говорит об эффективности их процессов документирования. Что касается инструментов, то здесь доминирует Swagger с долей 84%.
2/3
Примерно две трети тех, кто использует автоматизацию, все равно вынуждены вручную дополнять сгенерированный контент. Автоматизация ускоряет базовые задачи, но для формирования контекста и персонализации материалов важен человеческий вклад.
Языки и локализация
Основным языком технической документации по-прежнему остается английский. За ним с большим отставанием идет китайский, потерявший в этом году четыре процентных пункта. На третьем месте японский язык — его доля с прошлого года выросла на семь процентных пунктов.
На другие языки документацию переводят только 14% респондентов, а 8% рассматривают такую возможность. По сравнению с прошлым годом здесь нет существенных изменений.
Спасибо, что уделили время!
Если результаты исследования показались вам интересными, поделитесь ими с друзьями и коллегами.
Если у вас есть вопросы или пожелания, свяжитесь с нами по адресу surveys@jetbrains.com.