Краткое содержание. Июнь

- Write the Docs опубликовали результаты опроса про зарплаты технических писателей 2020. Опрос проводят второй год. В 2020 году опрос прошли 805 человек, что на 24% больше, чем в 2019 году. Про зарплаты в России там тоже есть, но очень мало опрошенных — 12 человек. Больше данных про зарплаты в России можно найти на Habr.

- В сообществе World Information Architecture проводят опрос, чтобы понять, как навыки информационной архитектуры относятся к тому, что вы делаете.

- Сразу несколько компаний написали про обновление документации: PayPal — про планы обновления документации для разработчиков, Firefox — про редизайн контента для новой версии браузера, а Github — про новый интерактивный подход к документации.

- В чате технических писателей Alec Chakenov поделился списком книг для технических писателей, которые пишут на английском.

- Airbnb написали про типы лидеров в UX-писательстве. Выделили 6 типов: Team builder, Product strategy pro, Subject matter expert, Master of craft, Ways of working champion, UXpert.

- Курс A Beginner's Introduction To Structured Content & DITA XML. Часть курса про структурированный контент подойдет даже тем, кто не использует DITA. Бесплатно.

- Вебинар Figma Basics for UX Writers and Content Designers.

Планы на июль

- Митап Content Design London Academy Show and Tell. Бесплатно, онлайн.

- Конференция Content by Design. Платно, онлайн.

#полезныессылки

​​Встроенные хелпы Miro и Whimsical

Я уже писала про то, что мне нравится хелп Miro. Но всегда есть что добавить.

Кроме основного хелпа у Miro есть встроенный хелп. Такой хелп удобен, потому что пользоваться им можно без поиска в гугл, дополнительных вкладок в браузере и СМС. То есть в любой непонятной ситуации пользователь может открыть хелп в интерфейсе и решить свою проблему. У Miro во встроенном хелпе в разделе How-to собраны подсказки по работе с интерфейсом: как выбрать несколько объектов и нарисовать стрелки. Каждая статья — это gif с пояснением.

Whimsical (коллеги Miro, тоже делают whiteboard для совместной работы) сделали встроенный хелп с помощью возможностей своего сервиса. То есть они собрали описание базовых возможностей сервиса на whiteboard. На whiteboard несколько gif с пояснениями (опять) и задания, которые пользователь может попробовать выполнить сам по инструкции, но без обязательств, проверок никаких нет.

#makedocumentationgreat #примеризжизни

​​Динамическая документация Worldpay

Документация для разработчиков движется от “вот ссылка на Swagger” к “вот пошаговая инструкция специально для тебя”.

У Worldpay в документации для разработчиков есть виджет “Tell us what you need”. В виджете нужно ответить, как вы планируете работать с API, например, кто будет аутентифицировать клиента. После ответов на вопросы вы получаете описание подходящего процесса: схему процесса работы и инструкцию, что нужно сделать по шагам.

#makedocumentationgreat #developerexperience

Краткое содержание. Июль

- Анонс Reference docs 2.0 от Redocly. Там новый дизайн документации и Try it консоли, новый поиск, поддержка OpenAPI 3.1 и возможность для читателей самим настроить внешний вид документации.

- Adyen планируют выложить в открытый доступ API-explorer. Пока открыто только бета-тестирование. Контакты в их докладе на API The Docs Virtual.

- Исследование от STC про то, кто и что писал с тегом #TechComm в Twitter с 2016 по 2019. Основные темы, которые обсуждались: Adobe TC suite, STC и STC Summit, академическая TechCom, профессиональное развитие, DITA и Lightweight DITA, вакансии, документация для ПО и Write the Docs. В исследовании для каждой темы выделены популярные теги и наиболее активные участники.

- Плагин для работы с Markdown в VSCode от Salesforce.

- Статья Пять обязательных тестов контента для UX-писателей. Это а/б-тест, тест на читаемость, проверка экспертом, тест на выполнения задания и сортировка карточек.

- Статья про путь Frontitude, программы для редактирования UX-текстов.

- Вебинар ContentOps for Technical Documentation.

Планы на август

- Конференция Commit, доклады про документацию (раз и два). Бесплатно, онлайн.

- Вебинар Making Invisible Teams Visible. Бесплатно, онлайн.

#полезныессылки

Documentation is Dead, Long Live Documentation!

На конференции GitLab было 2 доклада про документацию:
- Use Gitlab to Deliver "Docs-as-Code" Technical Documentation, который очень похож на доклад этого же автора на Write the Docs Australia.
- Documentation is Dead, Long Live Documentation!, который меня зацепил, потому что я люблю слушать про опыт создания документации от не технических писателей. Тут 2 докладчика, менеджер и разработчик, которые рассказывают свои впечатления от создания документации в Confluence и переезде на другую систему документирования.

Чем не нравится Confluence

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

Чего хотят

- чтобы было легко писать и публиковать документацию
- был базовый набор возможностей (как вставка изображения и ссылки) и продвинутый (как вставка примеров кода)
- можно пользоваться с Web или IDE
- хороший поиск
- обратная связь прямо в процессе работы над документом

Команда понимала, что они могут это сделать и с помощью Confluence, но слишком сложно.

Что используют сейчас

Попробовали VuePress, но потом переехали Material for MkDocs. Документация хостится на GitLab Pages. Из дополнительных фичей интегрировали в MkDocs draw.io. Счастливы:)

Доклад можно посмотреть на Youtube, для тех кто пропустил.

#намвсемнужнапомощь

Курт Воннегут о технических писателях

В своей статье “Как писать со стилем” Курт Воннегут говорит, что технические писатели обучены почти ничего не раскрывать о себе в своих работах.

Цитата:
​​

Newspaper reporters and technical writers are trained to reveal almost nothing about themselves in their writings. This makes them freaks in the world of writers, since almost all of the other ink-stained wretches in that world reveal a lot about themselves to readers. We call these revelations, accidental and intentional, elements of style.

Несмотря на то, что Курт Воннегут писал свои советы не для технических писателей, если присмотреться, то в них что-то есть:
1. Найдите интересующую вас тему.
2. Не разглагольствуйте.
3. Не усложняйте.
4. Имейте мужество резать.
5. Звучите естественно.
6. Скажите, что вы имеете в виду.
7. Пожалейте читателей.

Снова про скриншоты

Я собирала исследования про то, как пользователи воспринимают контент и нужны ли им скриншоты вообще. Но в документации часто бывают не просто скриншот, а скриншот с дополнительными элементами, такими как рамочка или стрелочка. Технические писатели добавляют эти элементы, чтобы помочь читателю. Но помогает ли это читателю?
Michael Meng выясняет это в исследовании Effects of visual signaling in screenshots: an eye tracking study.

Как проходило исследование

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

Какие выводы

- Меньше ошибок при выполнении задания сделали те, у кого на скриншотах были дополнительные элементы.
- Время выполнения задания примерно одинаковое.
- Участники дольше и чаще фиксировали внимание на областях, которые были выделены дополнительными элементами.

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

Исследование не позволяет сделать выводы о том, какие дополнительные элементы на скриншотах эффективны для направления визуального внимания пользователя, а
какие нет.

#экспериментыналюдях

Краткое содержание. Август

- В Cloud Native Computing Foundation Community Awards 2021 включили номинацию Top Documentarian.

- Статья про то, должны ли технические писатели получать больше разработчиков.
Документация является неотъемлемой частью продукта, как и код. Поэтому работа технических писателей должна оплачиваться наравне с разработчиками. Согласно опросам, средние базовые зарплаты разработчика и технического писателя в США совпадают. Но это средние базовые зарплаты, у 25 % разработчиков зарплаты выше среднего, нет данных про такие же зарплаты для технических писателей. Статью обсуждали в Twitter и Slack.

- Статья Sarah Maddox про связь проклятия знания, синдрома самозванца и метазнания.
Если мы не понимаем, как много мы знаем и что это может кто-то не знать (проклятие знания), то можем думать, что другие люди знают намного больше нас и мы не заслуживаем достигнутого успеха или похвалы (синдром самозванца). Знание того, что мы знаем, — это метазнание. Прокачать свое метазнание можно через менторство или блог.

- Статья BBC про исследования UX-текстов. Часть 1 и часть 2.
В ней собраны различных тесты для текстов и метрики, на которые стоит обратить внимание, например: понимание текста и восприятие бренда, время, проведенное на странице, % пользователей, которые успешно или нет выполнили какое-то действие.

- Статья про пользу совместной работы технических и UX писателей.
Совместно легче поддерживать единый стиль и консистентность между документацией и интерфейсом, можно вычитывать друг друга, обмениваться хорошими формулировками и знаниями о продукте. А еще технические писатели могут объяснять сложные штуки понятнее, чем разработчики.

- Scott Kubie отвечает, обязательно ли быть носителем языка, чтобы преуспеть в качестве UX-писателя.
У неносителей языка есть преимущества при работе над контентом для международной аудитории или контентом, который необходимо будет перевести на несколько языков. Есть и недостатки, неноситель может допускать ошибки, но такое бывает и с носителями языка.

- Статья про то, что создателям контента не хватает термина для названия специальности.
В отрасли нет единого мнения по поводу названия ролей и отличий между ними. Примеры названия роли: Content strategy, Content design, UX writing, ContentOps, Content marketing, Content management, Content engineering, Digital communications, Technical communications, Web content creation, Conversation design.

Планы на сентябрь

- Митап Good vs. Bad API Documentation: How API Documentation Drives Service Adoption. Бесплатно, онлайн.

- Вебинар What does documentation quality really mean and how do we improve it?. Бесплатно, онлайн.

- Секция докладов про документацию на конференции React Finland. Бесплатно, онлайн.

- Воркшоп Docs-as-code: An AsciiDoc primer на конференции DevConf US 2021. Бесплатно, онлайн.

#полезныессылки

Хелп Infracost

Что David Nunez (менеджер документации из Stripe) и Stephanie Blotner (менеджер технических писателей из Uber) улучшили бы в хелпе Infracost, потому что они рассказали про это в видео.

🌟 Не хватает домашней страницы

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

🌟Говорите про результат

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

🌟Проводите исследования

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

🌟Больше исследований

Можно проводить пользовательские исследования еще до начала разработки фичи. Так делает Stripe. Создайте документацию, которая описывает процесс работы с будущей фичей, и протестируйте ее на пользователях.

🌟Сценарии использования

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

🌟Не пытайтесь описать все сразу

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

🌟Документация часть продукта

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

#хелплинч #makedocumentationgreat

​​Интерактивные инструкции Algolia

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

Что в нем есть:
- код, который запускается в браузере
- чуть-чуть документации
- подсказки, которые рассказывают, что нужно сделать, чтобы попасть на следующий шаг
- progress bar, чтобы следить, сколько шагов осталось до успеха
- результат, который можно скопировать и использовать

Другие примеры динамической документации для разработчиков можно подсмотреть у Stripe и Worldpay.

#makedocumentationgreat #developerexperience

Swimm

Swimm — программа для создания документации. Позволяет встроить написание документации в процесс разработки. Такой подход называется Continuous Documentation. Например, можно вставить в документацию кусок кода, когда этот код изменится в исходнике, он изменится в документации. Кроме кусков кода можно вставить в документацию имена файлов или переменных, они тоже будут обновляться вместе с исходным кодом. Если какой-то документ стал не актуальным после изменений кода, то программа отметит его.

Есть плагины для VSCode и IntelliJ. При использовании плагина в коде будут видны ссылки на документацию. Документация открывается в IDE, то есть рядом с кодом, без переходов на другие сайты.

Интерфейс и некоторый фичи похожи на Confluence, например то, как код добавляется в документацию.

Сейчас Swimm в бета тестировании. Видео о том, как начать работать.

#тулзы

Краткое содержание. Сентябрь

- Видеообзор Docusaurus и Backstage.

- Новый Gatsby 4 работает быстрее и появился server side rendering.

- Советы по карьере от UX-писателей из Google, Airbnb и Spotify.

- Цикл статей про метрики для технического контента. В части 1 рассказывается о том, как задавать вопросы, на которые вы хотите, чтобы ваша аналитика отвечала, и о инструментах, которые могут помочь в этом. Часть 2 и часть 3 разбирают подход к аналитике на примере разделов начало работы и how to. В части 4 собраны проблемы, с которыми вы можете столкнуться, когда измеряете технический контент.

- Статья Научно обоснованный дизайн контента. Дизайн контента определяет как вы размещаете элементы на странице или экране. Дизайнерские решения могут или подрывать и отвлекать пользователей от идей, передаваемых контентом, или усиливать и поддерживать идеи.
Научно обоснованный дизайн контента — это методология создания контента, который согласуется с тем, как люди естественным образом воспринимают и обрабатывают информацию. Эта методология объединяет знания из таких областей, как исследования зрения и офтальмология, неврология, когнитивные способности и исследования внимания, психофизика и психология. Научно обоснованный дизайн контента помогает принимать решения по дизайну контента, которые естественным образом облегчают обработку информации. Это позволяет пользователям тратить свое время, усилия и когнитивные ресурсы на успешное использование информации для достижения целей, а не на расшифровку и интерпретацию контента.

- Видео Собираем документацию на основе программной модели. Пример создания документации к коду из комментариев с помощью Sphinx. Исходники на Github. Спасибо @mdanilov, что поделился.

Планы на октябрь

- Конференция Write the docs Prague 2021. Платно, онлайн.

- Конференция apidays LIVE LONDON 2021. Бесплатно, онлайн.

- Вебинар 5 lessons in achieving scale when you’re a solo strategist. Бесплатно, онлайн.

- Митап Findability in the world of docs. Бесплатно, онлайн.

- Рассылка Conversation Design Challenge. Бесплатно, онлайн.

#полезныессылки

​​Описание ошибок Plaid

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

А вот что не часто можно встретить в API документации, так это детальное описание каждой ошибки, где есть:
- список методов, которые могут вернуть эту ошибку
- описание ошибки и почему она произошла
- пример ошибки
- чек-лист что делать с ошибкой

Еще из интересного в этой документации есть чек-лист для запуска проекта и диаграммы для объяснения user flow.

#makedocumentationgreat #developerexperience

The 2021 State of Software Quality

SmartBear опубликовали результаты опроса The 2021 State of Software Quality:

- 76% респондентов опроса используют стандарт OpenAPI.
- Самый популярный сервис для управления API — AWS API Gateway, но многие не используют ничего или создают собственные решения.
- Инструменты для создания документации API поднялись на 2-е место с 3-го в списке инструментов, которые нужны для создания API.
- Точная и подробная документация — это вторая по важности характеристика для API с точки зрения пользователей. А наиболее важные разделы в документации — это примеры, описание ошибок, аутентификация (тут все совпадает с результатами опросов прошлых лет).
- Большинство респондентов ответили, что в их компаниях есть формальный процесс документирования API. Утвердительно ответили как респонденты из крупных, так и из небольших компаний.
- Только 16% респондентов сказали, что у них есть технический писатель.

#developerexperience

Знаете ли вы, чего хотят ваши читатели?

Yoel Strimling провел несколько исследований, чтобы понять, что такое “хорошая документация” по мнению читателей и понимают ли это технические писатели.

1. Beyond Accuracy: What Documentation Quality Means to Readers
2. So You Think You Know What Your Readers Want?

Как проходили исследования

В первом исследовании собраны различные методологии, по которым можно оценивать “хорошесть” документации. Из них выбрали методологию Wang and Strong (1996 года) и выделили 4 характеристики, в каждой определили подкатегории:

- Содержание: данные должны обладать качеством сами по себе (точность, достовернось, объективность, надежность).
- Контекст: данные должны рассматриваться в контексте поставленной задачи (объем, полнота, релевантность, своевременность, ценность).
- Представление: данные должны быть хорошо представлены (лаконичнось, согласованность, понятность, интерпретируемость).
- Доступность: данные должны быть легко извлекаемыми (доступность, безопасность).

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

Какие выводы

Для читателей основные характеристики “хорошести” документации это:
- Точность
- Понятность
- Релевантность

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

#экспериментыналюдях

​​The F-word

Есть распространенный способ собирать фидбек у читателей — добавить в документацию вопрос “Помогла ли вам эта статья” или “Была ли полезна статья”. Задавая такой вопрос, сложно получить фидбек, который можно использовать, потому что информации не хватает.

В исследовании What Documentation Quality Means to Readers, кроме метрик “хорошести” документации, есть формула идеального фидбека. Фидбек должен быть содержательным и действенным (то есть его можно однозначно понять и применить).

Чтобы получить такой фидбек нужно задавать другие вопросы. Если следовать методологии Wang and Strong, то вопросы могут быть такие:
- Смогли ли вы найти информацию, которую искали?
- Была ли информация точной?
- Была ли информация легкой для понимания?
- Была ли информация релевантной?
Эти вопросы помогают измерить характеристики, которые читатели выбрали самыми важными в документации. Пример опроса из исследования.

Кроме самого исследования можно посмотреть видео или полистать презентацию выступления Yoel Strimling.

Краткое содержание. Октябрь

- Oпрос по зарплатам Write the Docs 2021. Принять участие можно до 20 декабря, результаты опубликуют в феврале 2022.

- Голосование DevPortal Awards 2021. Проголосовать можно до 7 ноября.

- Саммари API Specifications Conference 2021. В будущую спецификацию OpenAPI планируют включить Documentation driven development.

- Статья Chief Information Architect. Когда интернет только появился, люди, занимающиеся тем, что мы сейчас называем стратегией пользовательского опыта, исследованиями и дизайном, назывались информационными архитекторами. Сейчас роль информационного архитектора сводится или к выяснению навигации для сайтов, или к построению таксономии, онтологии, колец синонимов и прочего.
Есть много организаций, где никто не выполняет работу информационного архитектора для продукта в целом, даже если многие дизайнеры думают о информационной архитектуре своих проектов.Тем не менее кто-то в компании должен быть главным информационным архитектором и выполнять работу по отображению пространства проблем/возможностей, а также смысла и цели продукта в этой более крупной системе. Это может директор по продукту (CPO) или директор по дизайну (CDO).

- Статья Согласование содержания документации по продукту. Про то как SAP переделали свой сайт документации. Для этого они разобрались кто их целевая аудитория и что они ищут. Чтобы сгруппировать информацию в хелпе так, как ее легче будет найти пользователям, они использовали методику “сортировки карточек” — то есть попросили пользователей самих сгруппировать информацию, написанную на карточках, по категориям.

- Статья Content Operations 101. С точки зрения клиента компании имеют две задачи: сделать что-то полезное и сделать так, чтобы люди умели это использовать. Обучение клиента продукту — это контент. Продукт и контент нельзя разделить, потому что контент делает людей опытными пользователями продукта. Content Ops — это системы и процессы, которые эффективно передают контент от мозгового штурма команды к клиенту. Когда у ваших сотрудников есть согласованные процессы и системы, им не нужно думать о том, как их контент доходит до клиентов, они могут сосредоточиться исключительно на качестве контента.

Планы на ноябрь

- Церемония DevPortal Awards.Бесплатно, онлайн.

- Митап The Language of Care. Бесплатно, онлайн.

- Митап Docs for Developers: A conversation with the authors. Бесплатно, онлайн.

- Семинар Certified Simplified Technical English. Платно, онлайн.

- Митап Contract Technical Writing: A Survival Guide. Бесплатно, онлайн.

- Митап The Value of ML Documentation. Бесплатно, онлайн.

- Митап Social and Semantic Technical Documentation. Бесплатно, онлайн.

#полезныессылки

API Explorer DocuSign

API Explorer и API Request Builder — это части портала разработчика DocuSign.

С их помощью можно:
- протестировать API пока читаете документацию, не написав ни строчки кода
- убедиться, что в документации все верно и ты все правильно понял
- написать первый прототип быстрее, потому что уже есть код, который можно использовать

За этот год DocuSign запустили новую версию API Explorer, потом доработали ее, а потом создали API Request Builder.
Я не смогла найти информацию о том, какие инструменты DocuSign используют, а жаль.

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

#makedocumentationgreat #developerexperience

API Explorers or Try it

Продолжу про API Explorer. Вот у каких компаний мне удалось его найти:

- Facebook API Explorer. Доступен только после регистрации. Без регистрации можно посмотреть инструкцию к нему.

- Asana API Explorer. И них у тоже есть инструкция к нему.

- Google API Explorer и инструкция.

- Adyen API Explorer. Они планируют выложить его в открытый доступ, но пока еще нет.

- DocuSign API Explorer и API Request Builder. Писала про них выше.

Как можно сделать самим

Вам понадобится Open API спецификация, потому что все инструменты, которые я знаю, за основу берут ее.

Потом можно взять готовое и платное решение:
- APIMATIC
- Redocly
- Apiary

Или воспользоваться чем-то бесплатными и доработать:
- Swagger UI или он же, но в более современном дизайне
- RapiDoc
- Readme
- Rhosys
- DapperDox
- Adyen API Explorer, но тут нужно подождать, пока его выложат в open source

#developerexperience #тулзы

Эмоций разработчиков по отношению к документации

Группа ученых из университета Indian Institute of Technology Tirupati провела эмоциональный анализ комментариев в коммитах, связанных с документацией.

- Understanding Emotions of Developer Community Towards Software Documentation, 2021 год
- Видео версия

Как проходило исследование

Ученые взяли 10 000 комментариев из коммитов, которые относятся к файлам README или файлам с расширением .txt или .md. Проанализировали слова, которые используют разработчики, и связали эти слова с эмоциями. Чтобы распознать эмоции использовали методологию NRC Word-Emotion Association Lexicon. Она позволяет определить 8 эмоций: гнев, ожидание, отвращение, страх, радость, печаль, удивление, доверие. Если какой-то комментарий выражал несколько эмоций, то выбирали более сильную.

Примеры того, какие комментарии соответствуют каким эмоциям, жирным выделены слова, которые характеризуют эмоцию:

- Improve duplicate torrent detection — доверие
- README is better short-n-sweet — радость
- Improved test framework, added missing dependencies — страх
- Make usage instructions more clear — ожидание
- drop support for older versions — печаль
- Location support (backward compatibility broken) — гнев
- plugin-browser-for-bbpress: A stupid bug. Tagged version 0.1.9 — отвращение
- Didn’t expect this to actually become a thing — удивление

Какие выводы

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

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

То, что доверие — самая частая эмоция, может означать, что:
- большинство разработчиков доверяют существующей документации
- обновления документации считается разработчиками правильным действием
Высокое доверие может быть причиной того, что разработчики вносят лишь незначительные изменения в существующую документацию.

P.S. Я не считаю, что исследование дает полную картину, так как в нем учтены только те, кто внес изменения в документацию. Но мне было интересно узнать их эмоции и понравился подход.

#экспериментыналюдях

Краткое содержание. Ноябрь

- Canonical (делают Ubuntu) опубликовали свои планы по преобразованию документации. За основу документации берут фреймворк Diátaxis. Считают, что документация очень важна. Планируют создать и поддерживать техническую документацию и практику документирования, которые будут представлять собой стандарт в отрасли.

- Github опубликовали ежегодный отчет. Документация часто является недостаточно обеспеченной областью проектов, несмотря на то, что она имеет решающее значение для привлечения новых участников, повышения качества работы и создания общего понимания. Разработчики видят примерно 50% повышение производительности благодаря простой в использовании документации.

- Postman опубликовали 2021 State of the API Report. Документация один из топ 4-х факторов, которые учитываются при интеграции с API. Главным препятствии для использования API назвали отсутствие документации, так ответили 55 % респондентов. Наиболее полезным улучшением в документации API – это улучшенные примеры, примеры кода и стандартизация.

- Confluence добавили возможность вставить несколько Excerpt macros с одной и той же страницы.

- DITA контент теперь можно публиковать с помощью mkdocs.

- А в Ditto (инструмент для работы с текстами в интерфейсе) можно добавлять переменные в текст.

- Redocly рассказали про преимущества их VS Code extension.

Планы на декабрь

- Вторая часть вручения DevPortal Awards. Бесплатно, онлайн.

- Митап Tempo presents: Scaling your content team. Платно, онлайн.

- Митап Delightful Editorial Experiences. A Sanity.io Open House. Бесплатно, онлайн.

- Адвент календарь про лучшие практики Confluence от k15t.

#полезныессылки