Tools

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

Для документации

- Paligo. В эту программу постарались вместить все, что нужно техническому писателю: единый источник, фильтрация контента, публикация в разных форматах, версионирование, ветки. Интегрируется с кучей всего, например, можно публиковать в Zendesk Guide, GitHub или BitBucket. Есть менеджмент переводов, мне особенно понравился менеджмент скриншотов для разных языков.
🤑Бесплатная пробная версия на 30 дней, а еще подробный хелп и видеоуроки.

- Elevio. Это не просто CMS (content managment system), a целый набор инструментов для интеграции справки в интерфейс. Например, с помощью инструмента Helpers можно сделать контекстную справку (к каждой странице интерфейса можно добавить какую-то статью хелпа) и всплывающие подсказки (к какому-то элементу интерфейса можно добавить поясняющий текст). Обычно для создания всех этих штук нужно привлекать разработчиков, а тут можно без. Еще есть интеграция с разными чатами, например, Intercom. В хелпе пишут про поддержку многоязычного контента и даже что-то про автопереводы, но я не пробовала.
🤑Бесплатная пробная версия на 14 дней. Для регистрации мне понадобилась почта на домене .biz.

Для текстов интерфейса

- Strings. Решает проблему, когда вы увидели опечатку в интерфейсе и нужно опять просить разработчика что-то поправить. Подключаете Strings к Github, писатель редактирует тексты в Strings, оттуда они попадают в Github, а там уже разработчики сами как-то с этим пулреквестом разбираются.
🤷‍♀️Выглядит удобно, но я не попробовала, потому что у них закрытое бета-тестирование.

- Frontitude. Frontitude интегрируется с Figma (программа, где работают дизайнеры). Тексты автоматически попадают из Figma в Frontitude. Затем писатель работает с текстом только во Frontitude: редактирует, согласовывает и обсуждает. При этом текст всегда можно посмотреть в текущем дизайне без перехода в Figma. Суперфишка этого приложения — это контроль голоса и тона. В прошлом посте писала, что такое есть только у Grammarly, но вот еще один пример. Обещают сделать интеграцию с другими дизайнерскими программами: Adobe Xd и Sketch.
💸Есть бесплатная версия.

- Writeon. Позволяет отредактировать текст на любом сайте. Это почти как поправить текст через Инструменты разработчика, только не нужно открывать код страницы. А еще вы сможете поделиться ссылкой на сайт с новым текстом.
🤑Бесплатная пробная версия на 14 дней.

Для переводов

- Phrase. Я не специалист в локализации, поэтому просто посмотрела. Мне понравилась возможность переводить контент прямо на сайте, сразу понятно, влезет текст или нет. Вот демо, можете сами попробовать. И куда же теперь без плагинов Figma и Sketch. С помощью плагинов можно выгрузить текст с макетов дизайнеров, перевести его и загрузить обратно.
💸Есть бесплатная версия.

#тулзы

​​Хелп Ситимобил

Посмотрим, как сделан хелп для пользователей такси Ситимобил. Я не буду рассматривать весь хелп, а только одну статью «Как заказать поездку?». Ссылки на нее нет, но я прикрепила внизу скриншоты. Еще вы можете сами найти все в приложении Ситимобил ( ☰—>Помощь—>Популярные вопросы—>Как заказать поездку?).

Логика и структура

Весь хелп построен как ответы на часто задаваемые вопросы. Один вопрос = одна статья. Но в статье «Как заказать поездку?» есть другие вопросы. Это делает статью длинной, статьи больше экрана неудобно читать на мобильном. Еще это ломает логику пользователя. На свой вопрос он ожидает увидеть один ответ, а не несколько новых вопросов. Поэтому лишние вопросы лучше вынести отдельно, а здесь добавить ссылку на них.
Так как в статье описаны действия, которые нужно выполнять последовательно, то нужен нумерованный список. Лучше него для таких случаев еще ничего не придумали.

Точность

Точность — это когда всё работает именно так, как описано. Какие тут проблемы:
- Названия кнопок не совпадают в интерфейсе и в хелпе. В хелпе «Оформить заказ» в интерфейсе «Заказать такси». Кнопки «Далее» нет, есть кнопка «Готово», но ее можно не нажимать, после выбора адреса интерфейс все делает за вас.
- Ввести адрес в поле «Откуда», как предлагают в хелпе, не так просто. В приложении адрес определяется автоматически, поэтому поле «Откуда» заполнено, пользователь не сможет его найти.
- Сложности есть и с тарифами и опциями. В хелпе пишут: «После этого вам откроется страница с тарифами и опциями». Нигде в интерфейсе нет таких названий. Поэтому то, что Комфорт — это тариф, пользователю нужно догадываться, а догадываться пользователь не должен. Еще это предложение ничего полезного пользователю не сообщает, поэтому его нужно удалить.

Слова и фразы

В тексте есть:
- оценочные суждения (просто и легко);
- слова усилители (очень и обязательно);
- всякие пассивные штуки (вам откроется страница, стоимость поездки будет рассчитана);
- зоопарк терминов (поездка, такси, машина, заказ, автомобиль);
- канцелярит (адрес своего места нахождения и адрес места назначения, которые сложно не только правильно писать, но и выговорить);
- сложный термин (push-уведомления, потому что, если мы пишем для пользователя, который не смог заказать такси из приложения, то почему он должен знать про push-уведомления).
От этого нужно избавиться. Из зоопарка терминов оставим только такси (с глаголами будет: заказать такси и отменить такси).

Как можно сделать

Как заказать такси
1. Выберите, откуда вы хотите поехать. Для этого переместите синюю метку в нужное место на карте.
2. Введите конечный адрес в поле Куда.
3. Выберите способ оплаты. Для этого нажмите на кнопку 💳 Не выбрано.
4. Если нужно, добавьте дополнительные услуги, например, детское кресло или перевозку животных. Для этого нажмите на кнопку Пожелания. Некоторые услуги платные.
5. Нажмите кнопку Заказать такси.

Чтобы отменить такси, потяните экран снизу вверх и нажмите Отменить заказ. Отмена будет платной, если водитель уже приехал к вам.

Вопросы, которые у меня остались

Есть несколько моментов, которые я бы отразила в статье, но не знаю ответов.
- Что придет, если push-уведомления отключены у пользователя?
- Можно ли изменить способ оплаты после заказа такси?
- Как работает оплата по счетчику?

Почему нельзя все взять и удалить

Для тех, кому кажется, что все очевидно и такая статья в хелпе не нужна, у меня есть исследование от Nielsen Norman Group. Если коротко, компьютерные навыки пользователей хуже, чем вы думаете.

#примеризжизни #makedocumentationgreat #хелплинч

​​Про контент-стратегию

Контент-стратегия может восприниматься как термин из сферы маркетинга. Общими словами контент-стратегия — это про планирование и создание контента на основе потребностей пользователей, а контентом может быть что угодно (и посты в Instagram, и Readme на Github).

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

Но это не означает, что контент-стратег делает это все один. Он работает вместе с исследователями, дизайнерами, инженерами, менеджерами, собирает разную информацию и анализирует. В итоге, он составляет план действий, где в продукте нужен контент и в каком формате (готовый ответ для бота, страница в помощи, инфографика, виджет или что-то еще).
Здесь самое место для вдохновляющей цитаты Сары Ричардс (Sarah Richards), контент-дизайнера и основателя Content Design London:

Лучшие продукты создаются там, где люди открыты для совместной работы, чтобы найти лучшие решения. (The best products are created where people are open to working together to find the best solutions.)

А что технические писатели?

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

Что почитать

За один пост я тему не раскрыла, планирую продолжать, а пока вот почитайте:
- Content Design below the surface на Medium. Именно картинку из этой статьи я прикрепила к посту.
- Блог сайта gov.uk.
- Блог Content Design London. Основатель Content Design London Сара Ричардс (Sarah Richards) еще известна тем, что руководила контент-дизайном в gov.uk.

#contentstrategy #точкароста

Лучшая API документация

Оказывается есть целая премия «Лучшие ресурсы для разработчиков» с номинацией «Лучшая API документация». Так как это #запоздалыеновости, то подать заявку со своей документацией не получится, но с 15 сентября можно проголосовать за понравившийся вариант.

Вокруг очень много прекрасной документации, которая меня вдохновляет и учит новому. А еще помогает тренировать насмотренность, чтобы потом легче находить интересные способы подачи информации. Эта премия подтолкнула меня достать из закладок все примеры документации, которые мне чем-то понравились. Так как сюда я их публиковать не успеваю, то это будет на Github.

#makedocumentationgreat

​​​Снова про кассу

Нашла в Uniqlo хороший пример визуальной инструкции. У меня уже был пост про инструкцию для кассы самообслуживания и вот опять.

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

Что понравилось:
- про оплату картой (это важная информация) написали в самом верху и крупно
- у каждого шага есть цифра и глагол
- картинки помогают, активные объекты подсвечены красным

#бытовуха #примеризжизни

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

- 🇬🇧 Статья Почему мы переходим от контент-стратегии к контент-дизайну

В Facebook с 2009 года работают контент-стратеги, сейчас их 500 человек. Недавно они провели анализ рынка и поняли, что за это время термин «контент-стратегия» изменился. Сейчас контент-стратегия чаще всего относится к маркетингу. Поэтому команду контент-стратегии переименовали в команду контент-дизайна. Новое название лучше отражает задачи и роль.
Цитата: Мы действуем как контент-дизайнеры: люди, которые проектируют слова, концепции, системы и терминологию, голос и тон, и которые знают, насколько эти вещи важны для решения проблем людей, которые используют наши продукты по всему миру.

- 🇬🇧 Статья Размышление о тексте как о системе

О тексте в продукте нужно думать как о системе, то есть как о взаимозависимой группе элементов, образующих единое целое. У дизайнеров есть дизайн-система, аналогичную можно сделать для текста. Стайлгайд не равно система.
К сожалению в статье нет примеров, но автор статьи делает инструмент Ditto для работы над текстом интерфейса. В нем можно создать текст-систему, вероятно, пока не пробовала.

- 🇷🇺 Пост в Телеграм
Наблюдение про зелёных менеджеров, которые готовы царапаться за свои формулировки

Бываю менеджеры, которые пишут тексты сами, а потом держатся за эти тексты и не дают их исправить. Тут проблема не в редакторе, не вините себя. Можно попробовать аргументировать свою позицию, объяснить работу редактора или давить через главреда.

- 🇬🇧 Презентация Как UX-писатели могут снизить когнитивную нагрузку

Когнитивная нагрузка — это время и умственные усилия, которые пользователь тратит, чтобы понять информацию. Чем меньше сил пользователь потратит на понимание, тем лучше. Чтобы снизить когнитивную нагрузку: 1) не используйте двойное отрицание 2) пишите числа цифрами 3) пишите текст только тогда, когда он нужен 4) используйте настоящее время и активный залог.

- 🇬🇧 Подкаст Начните UX-писательство в вашей компании

История о том, как стать UX-писателем. Как объединить дизайн-систему и стайлгайд. Про пользу от встреч для обсуждения проекта с дизайнерами (design+writer jam session). Как объяснить значимость UX-писателя в команде: протестировать тексты и опираться на это, рассказывать про свою работу, объяснять решения, давать почитать статьи.

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

Red Hat Documentation

Red Hat собрали в одном репозитории стандарты и соглашения, связанные с документацией своих продуктов.

Что там есть:

- Инструмент newdoc, который создает файлы в формате AsciiDoc по шаблону Red Hat.
- Гайд по модульной документации. Red Hat строит документацию основываясь на user-stories (пользовательских сценариях). В гайде есть раздел с шаблонами.
- Гайды нескольких продуктов Red Hat. Тут можно прочитать и про файловую структуру документации этих проектов, и про настройку окружения для работы с документацией.
- Общий стайлгайд.

#гайд

Adobe DITAWORLD 2020

Опубликованы доклады с конференции Adobe.

Для меня самыми интересными были:

- Beyond the OT. Sarah O’Keefe, CEO at Scriptorium
О том, можно ли из DITA OT получить что-то кроме стандартных PDF и HTML. Например, InDesign, PowerPoint или JSON.

- Customer Experiences – Powered by AI. Elliot Sedegah, Group Product Marketing Manager Adobe
Как можно упростить работу с контентом с помощью AI и что это изменит. Примеры: можно изменять контент под разные форматы и выделять основные слова из текста статьи и использовать их для тегов к статье.

- DITA, where art thou?. Kristen James Eberlein, OASIS DITA Technical Committee
Про жизненный путь архитектуры DITA и планы на будущее (DITA 2.0 и Lightweight DITA).

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

Tools 2

Продолжаю публиковать инструменты, которые я когда-то нашла, но попробовала только сейчас. Часть 1 тут.

Для документации

- Allwrite docs. Для тех, кто хочет сделать свою документацию из файлов Google Docs. Никакого языка разметки знать не надо, Allwrite docs сам конвертирует ваши файлы в html и markdown.
💸Бесплатно.

- PerfectIt. Плагин для Word. Находит опечатки и ошибки, проверяет пунктуацию в списках и таблицах, заглавные буквы и дефисы. Можно добавить свои правила.
🤑Бесплатная пробная версия на 14 дней.

- Readme. Генератор для API документации. Редактирование в markdown, импорт из Swagger или OpenAPI Spec, управление версиями, есть готовые темы. В платной версии есть встроенная аналитика для API.
💸Есть бесплатная версия.

- Write good. Линтер, который может найти пассивный залог и слова, которые не несут смысловой нагрузки в документации, например, just, really, very, extremely. Только en.
💸Бесплатно.

- IBM Style guide. Линтер, который проверяет документ на соответствие IBM writing style guide. Только en.
💸Бесплатно.

Для переводов

- Weblate. Поддерживает много форматов перевода, к переводу можно добавить контекст (скриншот или описание), можно настроить проверки качества перевода.
💸Есть бесплатная версия.


Мне про него рассказал @crrlcx, вот его отзыв:
Близок по возможностям к Phrase, Strings, Localise и Crowdin, к тому же может использоваться не просто как внешний сервис, но и как собственный.
На Weblate остановились из-за 2 вещей — его можно запустить у себя и он базируется на фреймворке django, в котором у наших разработчиков есть достаточно компетенций, чтобы вносить исправления или создавать плагины и не ждать вендора.
Плюсом, который не был очевиден сначала, оказалась открытость Weblate, так что наши внутренние исправления можно было предложить проекту сразу на github в виде пуллреквеста.

#тулзы

​​Хелп Miro

Что мне нравится ❤️ в хелпе Miro на примере статьи про инструмент Эмоджи. Я выбрала эту статью, потому что это рассказ об инструменте, a не пошаговая инструкция. Хороших пошаговых инструкций я видела много, хороших статей про инструменты — мало.

❤️ Логика и структура

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

❤️ Текст

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

❤️ Гифки

В хелпе много гифок, они здесь уместны, потому что показываю действия. Если эти действия начать описывать буквами, то получится не так понятно, например, поворот смайлика проще показать, чем описать.

Зачем тут хелп

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

#хелплинч #makedocumentationgreat

​​Developer experience

В Slack Write the Docs запостили платформу для экспериментов над разработчиками — Haxor. Я eе не пробовала. Мне нравится идея и подход, что-то можно реализовать и без платформы.

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

1. Вы выбираете задание, которое разработчик должен выполнить с помощью вашего API/SDK. Желательно на час.
2. Платформа подбирает разработчиков.
3. Разработчики выполняют задание и попутно записывают видео.
4. Платформа логирует действия разработчиков: код, который они пишут, и приложения, которые они используют.
В итоге вы получаете отчет с метриками, видео и логами действий разработчиков. Процесс повторяется каждый месяц.

Метрики

В отчете 4 метрики:
- время на выполнение задания;
- % ошибок во время выполнения;
- % выполнивших задание;
- счастье🤩.

И вот счастье — это самая интересная метрика. Она измеряется с помощью опросника, который когда-то придумали в IBM (Computer System Usability Questionnaire или PSSUQ). Разработчики оценивают насколько они согласны или не согласны с 16 утверждениями. Например такими:
- Пользоваться этой системой было просто.
- Было легко найти нужную мне информацию.
- Эта информация была эффективна, помогла мне выполнить задачу.
Получается, счастье разработчика — это когда есть понятная документация.

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

Краткое содержание. Ноябрь

- 🇬🇧 Статья Дизайн имени. Почему мы меняем названия должностей нашей контент-команды.

Shopify переименовали контент-стратегов в контент-дизайнеров. Потому что новое название точнее описывает работу и результаты, хорошо согласуется с должностями дизайнеров, понятнее для людей не из дизайна.
Цитата: Этот простой ярлык не меняет того, как мы делаем эту работу, но он помогает другим понять наше место в ней. Вот что делают хорошие имена.
В посте за октябрь писала про такое же переименование в Facebook.

- 🇬🇧Статья Насколько видео улучшает результаты обучения по сравнению с чтением?

В 2018 году MIT Integrated Learning Initiative (MITili) проверяла эксперимент. Участников разделили на 2 группы: одни смотрели видео-лекцию, другие читали текст лекции с диаграммами. Эффективность обучения померяли тестом на следующий день после обучения.
Выводы: эффективность обучения для видео и текста одинаковая. Влияние могло оказать то, что участники знали про проверку после обучения, поэтому были очень внимательны.
Другие факторы (недостаток сна или алкогольные напитки накануне вечером) не оказали статистически значимое влияние на обучение.

- 🇬🇧Статья Voice and tone

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

- 🇬🇧Статья Как дизайнер продукта и UX-писатель создают командную синергию


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

- 🇬🇧Статья Как создать гайдлайн по контенту в продукте

Пример создания гайдлайна по контенту силами одного UX-писателя за 10 месяцев.
Шаг 1. Провели исследование (посмотрели, что у конкурентов, поговорили с пользователями и командой, провели аудит всего контента). После исследования появилось понимание, чего не хватает контенту, что он должен делать, какими должны быть голос и тон.
Шаг 2. Написали гайдлайн. Примерный план разделов: цели и принципы, аудитории, голос и тон, грамматика и пунктуация, термины, глоссарий, компоненты.
Шаг 3. Рассказали на общей встрече компании. Чтобы помочь командам понять и начать использовать гайдлайн, провели семинары.

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

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

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

Я нашла онлайн-платформу 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.

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