Кто читает ваши документы?

Документы могут сделать или сломать продукт.

Согласно Опросу о состоянии баз данных 2022 года, документация является вторым по важности фактором, который разработчики используют при принятии решения о том, какую базу данных использовать. А в неофициальном опросе на конференции SciPy 2017 респонденты в среднем считали, что разработчики должны тратить на документацию примерно на 20% больше времени.

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

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

Неправильные персонажи

Я работаю в компании по работе с базами данных. Когда я думаю о наших пользователях, я думаю о:

  • Инженеры-программисты
  • DevOps-инженеры
  • Администраторы базы данных
  • Инженеры данных
  • Аналитики данных
  • Ученые данных

…и так далее.

Это естественный подход.

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

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

Три личности, которые имеют значение

То, как я использую документы, не сильно изменилось за эти годы.

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

Не все такие.

В кратком изложении, опубликованном в Протоколах семинара Дагштуля за 2007 год, Стивен Кларк обсуждает, как наблюдение за конечными пользователями инженеров-программистов (вспомните конечных пользователей API и SDK) в течение года в Microsoft привело его команду к разработке трех персонажей:

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

Я прагматичный разработчик. Кто из них вы?

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

Это согласуется с собственным наблюдением Кларка: «Стили работы, которые мы описали в образах персонажей, разделяют люди с разным уровнем знаний и образования. Это не тот случай, когда кто-то начинает как оппортунистический разработчик, а затем становится прагматичным разработчиком после получения определенного уровня опыта и знаний».

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

Я все время писал не для тех людей.

Влияние на дизайн контента

Хорошая документация строится на основе практических автономных примеров.

Прагматичные и систематические разработчики будут использовать более длинные документы, такие как учебные пособия и концептуальные руководства. Но оппортунистическим разработчикам мало интересно читать объяснение из тысячи слов.

Солидный пример предлагает хорошую точку входа для всех персон:

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

Хороший пример:

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

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

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

Они вдохновляют точки входа.

Хотите, чтобы кто-то использовал ваши документы? Найдите хороший первый пример, ориентированный на их нужды. Сделайте его автономным, чтобы они могли использовать его без трения. Предоставьте щедрые ссылки на дополнительные ресурсы.

Затем сделайте так, чтобы эту точку входа было легко найти.

Понравилась эта статья? Подпишитесь на мою рассылку и будьте первым, кто прочитает все мои истории.