​​Инструкции совсем как у Икея

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

Я нашла онлайн-платформу Cadasio, с помощью которой можно создать из 3D моделей картинки или анимированные видео.

Как это работает:

1. Вы загружаете CAD-файл 3D модели в Cadasio.
2. Выбираете правильный ракурс. Можете отсоединить какую-то деталь из модели, добавить стрелочки или текст.
3. Когда все готово, делаете снимок. Чтобы сделать анимированное видео, нужно последовательно сделать снимки для нескольких шагов.

В итоге вы получите ссылку на изображение или QR-код. Потом можно отредактировать изображение в программе, но ссылка останется та же.

Программа бесплатная для личного использования. Есть похожие платные аналоги, например, Solidworks Composer и Catia Composer.

#tools

Как пользователи воспринимают контент

Продолжу тему визуальных инструкций или комиксов. Для вдохновения я опубликовала свою подборку визуальных инструкций на 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.

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

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

Лучшие примеры технической коммуникации

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

Про судейство на Technical Communication Competitions

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

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

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

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

Категории

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

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

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

Про судейство на Technical Communication Competitions

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

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

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

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

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

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

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

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

Критерий 3. Визуальные элементы

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

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

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

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

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

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

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

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

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

Всемирный день информационной архитектуры

Ежегодно в феврале проходит всемирный день информационной архитектуры. Информационная архитектура — термин со множеством определений. Можно говорить, что информационная архитектура — это декомпозиция и структура контента, например, так говорят про информационную архитектуру 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.

#вестникмитапов

Про редизайн документации GitLab

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

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

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

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

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

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

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

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

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

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

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

Про судейство на 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.

❌Ваши иллюстрации размыты.
✅Иллюстрации размыты.

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

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

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

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

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

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

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

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

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

Краткое содержание. Май

- 🇬🇧 На конференции Google I/O прошел семинар про UX Writing
Это практическое занятие про создание текста для приложения, который помогает пользователю. Разбирают, что такое голос и тон, как их выбрать, показывают, как создать матрицу контента. Дополнительно есть текстовая версия.
Важно, что этот семинар прошел на конференции Google I/O, это улучшает видимость деятельности по созданию текстов в IT и показывает, сколько работы стоит за каждой фразой в приложениях Google.

- 🇬🇧 Airbnb обновили хелп и онбординг
Полный список обновлений опубликован тут.

- 🇷🇺 Максим Ильяхов написал про Tone of Voice
Согласна полностью. Нельзя скопировать у кого-то голос. Я растянула эту мысль аж на 2 поста (раз и два).

- 🇬🇧 Подкаст UX-писательство и документация
Рассказывают про то, какую (внутреннюю) документацию и когда создавать, чтобы было легко работать с текстами в интерфейсе. Базовый набор: глоссарий, стайлгайд, гайдлайн по тону и голосу, набор часто используемых текстов. Расширенный: описание процесса работы ux-писателя (каким он должен быть на ваш взгляд) и шаблон исследования, который включает черновые варианты текстов.

- 🇷🇺 Школа по документированию Xsolla 2021
Бесплатно и онлайн. Берут без опыта и с опытом от года. Для поступления нужно сделать тестовое задание.

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

Менторство

Я начинала свою карьеру как единственный технический писатель в компании. Сама разбиралась, что нужно учить, чтобы расти в карьере. Когда я стала работать в команде, расти стало проще — помогал фидбэк и опыт коллег. Поэтому я считаю, что общение с ментором, который уже прошел похожий путь, сложно заменить. Про то, кто такой ментор, хорошо написано в канале No Flame No Game.

Если вы готовы поделиться с кем-то своим опытом или ищете себе ментора, то вот проекты, где можно это сделать:

- Society for technical communication
Для кого: для технических писателей и специалистов по технической коммуникации.
💸 Бесплатно.

- UX.Coffee.Hours.
Для кого: для UX-специалистов, есть UX-писатели и контент стратеги.
💸 Бесплатно.

- ADPList
Для кого: для дизайнеров, есть UX-писатели и контент стратеги.
💸 Бесплатно.

- UX Writing Hub
Для кого: для UX-писателей, ищут только менторов.
🤑 Бесплатно для менторов, для менти — стоимость включена в обучение в UX-writing academy.

- GetMentor
Для кого: для всех, есть технические писатели.
🤑 От “бесплатно” до “по договоренности”.

- No Flame No Game
Для кого: для всех, есть технические писатели.
💸 Бесплатно.

#точкароста

​​Хелп Stripe

Что мне нравится 💜 в хелпе Stripe. Я выбрала Stripe, потому что мне все говорят, что у них классная документация, но не говорят, почему.

💜 Много примеров

Хорошая документация для разработчиков не бывает без примеров кода. У Stripe примеры кода есть для всего и встроены в документацию. А еще есть готовые проекты, которые можно клонировать и начать работу. Чтобы разобраться с чужим кодом было проще, есть динамические примеры, в которых объясняется каждая строчка кода. Отдельно собраны готовые no-code решения.

💜 Не только про Stripe

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

💜 Видео

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

💜 Навигация

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

#хелплинч #makedocumentationgreat

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

- 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, для тех кто пропустил.

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