Ученые узнали, чего на самом деле хотят разработчики от документации

Вот исследования от настоящих ученых из Merseburg University of Applied Sciences:
1. Документация API: Чего хотят разработчики?, 2018 год.
2. Оптимизация документации API: рекомендации и их эффективность, 2020 год.

What do software developers want?

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

Исследование показывает, что разработчики подходят к новым API с двумя разными целями:
- понять, следует ли выбирать API для решения конкретной задачи;
- использовать API для выполнения задач.

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

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

Но все не так просто, при изучении API у разработчиков возникают проблемы:
- Неточная документация или документация с ошибками.
- Непонятная документация.
- Трудно найти информацию (определить, как API должен использоваться для решения конкретной проблемы или с чего начать работу).
- Работа с API требует знаний в предметной области, но этой информации нет в документации (например, для работы с API биржи надо понимать, как эта биржа работает).

Если разработчики сталкиваются с проблемой, то большинство пойдет гуглить, только 30% будет читать документацию.

Что с этим делать?

На основе первого исследования и исследований других авторов во втором исследовании составили рекомендации по разработке документации API и проверили их эффективность.

То есть ученые взяли реальный API c реальной документацией и переписали документацию. Потом попросили разработчиков выполнить несколько задач c помощью API. При этом одним дали старую документацию, а другим — новую. Меряли точность выполнения задач, время выполнения и время, затраченное на документацию и на ресурсы вне документации.

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

У разработчиков были замечания к обеим версиям документации.

Какие выводы

Рекомендации по разработке документации API, которые описаны в исследованиях, соответствуют best practice в индустрии (как курс Тома Джонсона про API). Нормально делай — нормально будет 🙂

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

​​Devportal Awards 2021

В прошлом году я писала про премию «Devportal Awards», но с опозданием, подать заявку на участие было уже поздно.

В этом году публикую вовремя, подать заявку на участие можно до 30 июля. Номинаций стало больше, например, появились номинации «Лучший внутренний Devportal»
и «Лучшая модель монетизации».

Голосование за лучшие порталы начнется в сентябре.

#makedocumentationgreat #developerexperience

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

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

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

#makedocumentationgreat #developerexperience

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

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

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

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

#makedocumentationgreat #developerexperience

​​Описание ошибок 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

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 #тулзы

The Best Developer Portals of 2021

Объявили победителей премии The Best Developer Portals. Всего было номинировано 49 порталов. Про процесс оценки порталов жюри рассказали в интервью.

Кто победил

Лучший портал выбирали среди тех порталов, которые уже получили награду в других категориях. В итоге победили:

- Ably Developer Platform – лучший девпортал для малого и среднего бизнеса.
Жюри оценили простоту и удобство сайта, хороший баланс между визуальными эффектами и деталями, а также ориентированность сайта на разработчиков. В прошлом году Ably заняли второе место. Еще они выиграли Best API Business Model и Best Use of API Gateway Integration.

- FusionCreator Developer Portal – лучший девпортал для крупных компаний.
Тут жюри отметили подробную справочную документацию, хороший раздел начало работы, множество видео контента, и три различных типа навигации в документации. Еще они выиграли Best Findability of Products.

Победители в других номинациях

- BT API Developer Portal – лучший внутренний девпортал, потому что содержит все, что ожидается от отличного портала разработчиков, например, примеры кода и песочницу, а также множество полезной информации для внутренних разработчиков. Для внутренних разработчиков предусмотрен упрощенный процесс доступа к API. Демо портала.

- platformOS – лучший онбординг и лучший процесс редактирования, жюри отметили процесс публикации, который включает автоматизированное тестирование документации, и весь рабочий процесс, который следует принципам docs-as-code. Демо портала.

- Plaid's Developer Portal and Documentation – лучшая API Reference документация и лучший дизайн, потому что сайт хорошо структурирован и хорошо использует пустое пространство, а контент легко быстро понять благодаря множеству примеров кода.

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

- Xsolla – лучшая локализация девпортала, поддерживают 6 языков. Доклад Xsolla про локализацию на Apidays LIVE Paris.

- BNI API Digital Services – приз зрительских симпатий.

Полный список победителей.

#developerexperience

Docs for Developers

Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.

Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:

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

Еще обсуждение книги с авторами можно послушать в подкасте Write the Docs.

Что зашло

- Легко и быстро читается.

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

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

- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).

Не зашло

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

- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.

Однако

Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.

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

Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.

Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.

#developerexperience