Ученые узнали, чего на самом деле хотят разработчики от докуме | Shut up and write

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

Вот исследования от настоящие ученые из 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