Shut up and write

2021-04-23 14:00:53 Ученые узнали, чего на самом деле хотят разработчики от документации

Вот исследования от настоящие ученые из 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 Открыть/Комментировать

2021-04-09 14:01:07 - Пишите комментарии о записи, а не о себе. Вы можете писать о себе, если это имеет отношение к делу. Когда пишите о себе, то пишите от первого лица единственного числа. Опустите слова вроде “я думаю” и “по-моему".

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

Я думаю, что рисунок на стр. 17 дает прекрасный обзор всего производственного процесса.
Рисунок на стр. 17 дает прекрасный обзор всего производственного процесса.

- Формулируйте комментарии как предложения, а не приказы. Например, начните предложение со слов “рассмотрите ...” и “подумайте…”. Добавьте обоснование ваших предложений.

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

Всегда используйте нумерованные списки в процедурах.
Рассмотрите возможность использования нумерованного списка вместо маркеров для шагов установки на стр. 6. Если вы не хотите использовать нумерованный список для процедурных шагов, таких как длинный список задач на стр. 16, рассмотрите возможность добавления флажков. Пользователи могут распечатать PDF-файл и отметить каждый шаг. В качестве альтернативы можно озаглавить раздел “Обзор задач настройки”, чтобы читатели не задавались вопросом, почему шаги не имеют цифр.

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

2021-04-09 14:01:07 Про судейство на Technical Communication Competitions

Продолжение про фидбек, который дают судьи. Прошлая часть тут.

Про что писать в фидбеке

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

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

Как правильно написать фидбек

Цель фидбека — это помочь сделать документ лучше. То есть нужно дать конкретные советы, а не оценку.

Правила “как писать фидбек” вроде очевидные и все их знают, но почему бы не повторить.

- Поддерживайте свои комментарии конкретными примерами и ссылками.

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

Дизайн загроможден.
Рассмотрите разбиение информации на рис. 17 (стр. 41) на четыре диаграммы, каждая из которых представляет одну из основных подсистем. Каждая из диаграмм может быть на своей странице вместе с легендой. Это сделает диаграммы менее загроможденными, так что пользователи смогут легче найти то, что они ищут. Также рассмотрите возможность применения аналогичных методов упрощения к таблицам на страницах 46 и 48 и к объяснению XML-схем на страницах 67-84.

Графика хорошо сделана.
Графика хорошо использует выноски — например, на страницах 5 и 10.

В индексе требуется больше записей.
Вы можете улучшить индекс, добавив записи с альтернативными формулировками. Например, на страницах 3-25 есть заголовок Отправка файла. В индексе есть запись “отправка файла”, но нет записи “файл, отправка”. Альтернативная формулировка поможет пользователям, которые ищут слово “файл” в индексе.

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

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

Кто бы ни написал текст этого пособия, он должен вернуться во второй класс на курсы повышения квалификации по английскому языку!
Обсудите возможность добавления редактуры в цикл выпуска документации, чтобы исключить ошибки, такие как использование “it's” для “its” и “demonstration's” для “demonstrations” в главе 4, использование “descendent” для “descendant” в главе 5.

Ваши иллюстрации размыты.
Иллюстрации размыты. Открыть/Комментировать

2021-02-17 14:00:28 Про редизайн документации GitLab

GitLab считает, что отличная документация для их проекта — это необходимость. Чтобы сделать свою документацию отличной, они провели исследование о том, зачем пользователи приходят в их документацию и что в ней сейчас не так. Проанализировали эти данные и сделали на основе них редизайн сайта документации.

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

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

Дальше немного красивых циферок и рандомных фактов.

Нашли ли пользователи в документации то, что искали

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

Зачем пришли в документацию

- 35% искали инструкцию.
- 24% открыли страницу, которую используют как референс.
Большинство пользователей переходят в документацию из Google или сохраненных страниц.

Проблемы, которые выявило исследование

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

#экспериментыналюдях #makedocumentationgreat Открыть/Комментировать

2021-02-03 15:00:36 Всемирный день информационной архитектуры

Ежегодно в феврале проходит всемирный день информационной архитектуры. Информационная архитектура — термин со множеством определений. Можно говорить, что информационная архитектура — это декомпозиция и структура контента, например, так говорят про информационную архитектуру DITA. Можно говорить, что это способ, которым мы упорядочиваем части чего-то, чтобы сделать его понятным, как в книге How to Make Sense of Any Mess. Эти определения друг друга не исключают, они смотрят с разных сторон.

27 февраля онлайн пройдет World IA Day London 2021. Тема этого года «Curiosity».
Про что будем говорить:
- Использование дизайн-мышления для улучшения MVP (Ioannis Nousis, Interaction Designer at Google)
- Внедрение CI/CD для публикации документации (David Bailey, Information Architect at Snyk)
- От хаотического контента к хорошо сбалансированному графу контента (Dr Ian Piper, Owner of Tellura Semantics)
- Системное мышление на практике (Bryn Ray, Consultant, Experience Transformation at American Express)
- Peter Morville (соавтор книги по Information Architecture for the World Wide Web)
- John V Willshire (cоздатель smithery.com и изобретатель артефактных карт)

Участие бесплатно, зарегистрироваться можно по ссылке. Митапы в других городах можно найти на сайте WIAD.

#вестникмитапов Открыть/Комментировать

2021-01-29 15:00:36 Критерий 3. Визуальные элементы

Про то, насколько эффективно визуальные элементы поддерживают контент.

- Макет и презентация. Насколько аккуратной и визуально сбалансированной является страница, экран или пользовательский интерфейс? Насколько хорошо макет использует белое или пустое пространство? Насколько последовательным является использование графических элементов?
- Цвета и тени. Насколько последовательным является использование цвета или оттенков серого? Служит ли цвет или затенение для усиления смысла содержания?
- Типография. Насколько хорошо выбор шрифта поддерживает смысл и читабельность? Может ли пользователь изменять размер текста?
- Художественная работа (графика, таблицы, фотографии, анимация). Насколько хорошо диаграммы и иллюстрации поддерживают текстовое содержание? Насколько эффективны выбранные типы графических элементов? Правильно ли представлены и объяснены в тексте иллюстрации, таблицы и мультимедийные элементы? Правильно ли расположены элементы по отношению к тексту? Если есть анимация, то насколько она уместна и полезна, не отвлекает ли? Насколько хорошо анимация дополняет материал?
- Способ публикации или доставки информации (примеры способов доставки информации: печать, экран компьютера или телефона). Насколько уместен выбор способа доставки информации? Насколько этот способ эффективно используется? Насколько хорошо работа извлекает выгоду из особенностей выбранного способа доставки? Используются ли мультимедийные элементы (звук, видео, анимация, интерактивность) надлежащим образом для достижения этой цели? Являются ли элементы простыми в использовании и качественными (разрешение, частота дискретизация)?

Критерий 4. Доступность

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

- Доступность. Насколько хорошо контент соответствует принципам доступности? Принципы для неамериканских организаций и для американских организаций.
- Альтернативный доступ (только электронных работ). Может ли пользователь получить доступ к информации несколькими способами, такими как всплывающие подсказки (Alt text) или сочетания клавиш? Есть ли у аудио, видео и других нетекстовых элементов альтернативные способы доступа к информации (например, субтитры или стенограмма)?
- Размер шрифта, цвет и контраст. Насколько подходит размер шрифта и цвет для пользователей с плохим зрением? Позволяет ли выбор цвета дальтоникам визуально интерпретировать информацию?

Критерий 5. Учебный дизайн

По этому критерию оцениваются только учебные материалы.

- Цели обучения и оценки. Насколько четко определены цели и результаты обучения?
Имеет ли каждая цель обучения соответствующую проверку знаний, практику или учебную деятельность? Обеспечивают ли оценки как подкрепляющую, так и корректирующую обратную связь?
- Вовлечение учащихся. Вовлекают ли такие действия, как примеры, сценарии и демонстрации, учащегося в материал? Предусмотрен ли какой-либо метод для того, чтобы учащийся задавал вопросы?
- Метод обучения (для работ из категории самостоятельное компьютерное обучение, веб-обучение, обучение под руководством инструктора). Насколько уместен метод обучения? Используются ли различные учебные методы для представления информации?

В следующий раз расскажу про требования к фидбеку, который дают судьи. Открыть/Комментировать

2021-01-29 15:00:36 Про судейство на Technical Communication Competitions

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

Дальше сокращенный и вольный перевод формы, которую заполняют судьи.

Критерий 1. Как написан и отредактирован текст

Про то, как применяются основы хорошего письма и насколько стиль текста подходит для аудитории и цели.

- Техническая лексика. Объясняются ли аббревиатуры и важные термины там, где это уместно? Устранен ли ненужный жаргон (технические термины, известные ограниченной аудитории)? Насколько хорошо разработан глоссарий? Если его нет, то нужен ли глоссарий?
- Заглавные буквы, орфография и пунктуация. Являются ли заглавные буквы, орфография и пунктуация правильными и последовательными?
- Грамматика и синтаксис. Свободен ли текст от грамматических ошибок?
Насколько логично изложение? Логично ли то, как слова образуют фразы, фразы образуют предложения, предложения образуют абзацы, а абзацы составляют большие разделы?
- Последовательность. Параллельны ли элементы списка и заголовки по конструкции и стилю? Последовательно ли представлены другие подобные текстовые элементы с точки зрения выбора формулировок?
- Выбор слов. Насколько уместны стиль письма, уровень формальности?
Помогает ли выбор слов и фраз пользователям понять важность информации? Например, однозначны ли критические инструкции?
- Ясность и лаконичность. Насколько формулировки ясные и лаконичные? Не слишком ли формулировки скупые? Насколько уместны длина и сложность предложения для аудитории и цели?

Критерий 2. Информационный дизайн

Про то, как организован контент и удобно ли его воспринимать.

- Организация информации. Насколько отчетливо видна структура? Насколько она логична и последовательна? Разделен ли текст на подразделы или темы с понятными по заголовкам и подзаголовкам?
- Объем содержания. Насколько подходит объем материала для аудитории и цели?
Есть ли в документе вся необходимая информация?
- Навигация. Насколько легко пользователь может найти информацию? Насколько хорошо навигация помогает пользователю? Насколько интуитивно понятен интерфейс навигации? Правильно ли работают ссылки, кнопки и закладки? Сводит ли дизайн к минимуму необходимость прокрутки?
- Оглавление. Насколько точно и последовательно оглавление? Насколько хорошо верхние и нижние колонтитулы поддерживают информационную иерархию? Если оглавления нет, то нужно ли оно?
- Перекрестные ссылки. Перекрестные ссылки ведут на нужную страницу? Насколько хорошо текст перекрестной ссылки описывает целевую информацию? Если перекрестных ссылок нет, то нужны ли они?
- Индекс. Насколько хорошо построен и развит индекс? Предоставляет ли индекс альтернативные способы поиска материала, используя перекрестные ссылки и синонимы? Если индекса нет, то нужен ли он?
- Поиск (только электронные работы). Насколько интуитивно понятна работа поиска? Влияют ли регистр, опечатки и вариации слов на результаты поиска? Если поиска нет, то нужен ли он? Открыть/Комментировать

2021-01-22 15:00:31 Про судейство на Technical Communication Competitions

Взгляд со стороны судьи на то, как в Society for Technical Communication (STC) проходит процесс оценки работ на конкурсе по технической коммуникации. Но начну издалека.

Что такое техническая коммуникация?

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

По определению STC техническая коммуникация охватывает любую коммуникацию пo технической или научной теме. Они называют свое определение — либеральной интерпретацией.

Категории

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

Про процесс оценки

Подавая заявку на участие в соревновании, конкурсанты выбирают одну из категорий, рассказывают для кого предназначен этот материал и каких целей хотели достичь. Информация из заявки видна судьям.
Каждый судья оценивает работу по определенным критериям, фактически отвечает на вопросы форме. После заполнения форм судьи собираются вместе и обсуждают свои оценки. В итоге судьи должны прийти к общему мнению.
В судьи берут людей с разным опытом и стажем работы. Для меня было удивительно, что в команде, в которой была я, оценки совпали на 85 процентов, а там где не совпали, мы быстро договорились. На мой взгляд, в этом помогли четкие критерии оценки. Вот про них напишу подробнее в следующий раз.
Чтобы стать судьей можно подать заявку в одно из отделений STC. Обычно все встречи судей проходили офлайн, поэтому участвовали те, кто мог присутствовать лично. В 2020 все было онлайн, поэтому на локацию не обращали внимания. В 2021 скорее всего будет так же. Открыть/Комментировать

2021-01-15 15:00:36 Лучшие примеры технической коммуникации

Society for Technical Communication ежегодно выбирает лучшие примеры технической коммуникации. Это может быть справка, рекламный, информационный или учебный материал. На оценку влияют множество факторов: подходит ли документ выбранной категории и аудитории, есть ли ошибки и опечатки, удобно ли пользоваться оглавлением. Работы в одной категории не сравниваются друг с другом.

Вот лучшие работы этого года, которые выбрали в отделении Carolina (и которые доступны без регистрации):

- NASA & A Guide to Commercial Suborbital Flight Providers for Flight Opportunities
Категория: Рекламные материалы – Брошюра.
Аудитория: Аэрокосмические инженеры и исследователи, разрабатывающие технологии летных испытаний суборбитальных аппаратов.

- National Toxicology Program & Integrated Chemical Environment
Категория: Материалы для поддержки пользователей – Хелп (онлайн или встроенный).
Аудитория: Ученые, регуляторы и другие лица, которым необходимо получить доступ или просмотреть данные тестов и инструментов, используемых для оценки химических свойств и токсичности, аудитория имеет высшее образование и работают в области токсикологии и биохимия.

- Salesforce & Accelerate Your Sales Process with High Velocity Sales Video
Категория: Информационные материалы – Видео.
Аудитория: Клиенты и администраторы Salesforce.

- Salesforce & What’s Up with Whatsapp?
Категория: Информационные материалы – Видео.
Аудитория: Торговые представители.

- United States Environmental Protection Agency & Global Non-CO2 Emissions Projections and Mitigation: 2015-2020
Категория: Информационные материалы – Технический отчет.
Аудитория: Исследователи, заинтересованные в воздействии на климат источников, генерирующих выбросы парниковых газов, не связанных с CO2.

#makedocumentationgreat Открыть/Комментировать

2021-01-08 15:00:10 Как пользователи воспринимают контент

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

Мне интересно, работают ли такие инструкции на самом деле, помогают ли пользователю. И как пользователи воспринимают контент. Например:
- Нужен ли текст, если есть картинка? У Икеи текста почти нет.
- Нужна ли картинка, если есть текст?
- Как быстро можно понять картинку с текстом и без текста?
- Как расположить текст и картинку?
- Помогут ли GIF-ки или короткие видео сделать контент понятнее?

Исследований, которые говорят, как правильно нет. Но вот, что я нашла:

- Делайте четкие и детальные изображения, студенты в исследовании сначала сосредоточились на изображениях, а затем при необходимости обратились к тексту. Будьте кратки с текстом. Студенты предпочитали маркированные пункты с ключевыми терминами, выделенными жирным шрифтом. Инструкции с изображениями более эффективны, чем с видео, потому что в них легче найти конкретную информацию. Источник: Student preference for tutorial design | Mestre.


- Значимые изображения, которые поддерживают текст, полезны и привлекут внимание пользователя. Такие изображения хорошо работают как в зигзагообразном, так и в выровненном макете, потому что пользователи хотят тратить время на просмотр изображений, чтобы понять текст. Источник: Zigzag Image–Text Layouts Make Scanning Less Efficient | Nielsen Norman Group.


- Изображения или GIF-ки для каждого шага инструкции удобнее для пользователя, чем видео. Источник: How to Film and Photograph Online Content for Usability: UX Details for Videos and Images | Nielsen Norman Group.


- Текстовые и графические инструкции более эффективны, чем аудио и видео. Источник: Static vs. dynamic tutorials | Turner, Fuchs, and Todman.


- Видео — это дополнительный источник информации, не все пользователи будут его смотреть. Если у вас нет видео, а пользователям оно нужно, чтобы разобраться, они найдут видео в другом месте. Источник: Videos as Instructional Content: User Behaviors and UX Guidelines | Nielsen Norman Group.

Дополню подборку, когда найду что-то еще. Если знаете хорошие исследования по теме, пишите в комментариях.

#экспериментыналюдях Открыть/Комментировать