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

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

Курт Воннегут о технических писателях

В своей статье “Как писать со стилем” Курт Воннегут говорит, что технические писатели обучены почти ничего не раскрывать о себе в своих работах.

Цитата:
​​

Newspaper reporters and technical writers are trained to reveal almost nothing about themselves in their writings. This makes them freaks in the world of writers, since almost all of the other ink-stained wretches in that world reveal a lot about themselves to readers. We call these revelations, accidental and intentional, elements of style.

Несмотря на то, что Курт Воннегут писал свои советы не для технических писателей, если присмотреться, то в них что-то есть:
1. Найдите интересующую вас тему.
2. Не разглагольствуйте.
3. Не усложняйте.
4. Имейте мужество резать.
5. Звучите естественно.
6. Скажите, что вы имеете в виду.
7. Пожалейте читателей.

Снова про скриншоты

Я собирала исследования про то, как пользователи воспринимают контент и нужны ли им скриншоты вообще. Но в документации часто бывают не просто скриншот, а скриншот с дополнительными элементами, такими как рамочка или стрелочка. Технические писатели добавляют эти элементы, чтобы помочь читателю. Но помогает ли это читателю?
Michael Meng выясняет это в исследовании Effects of visual signaling in screenshots: an eye tracking study.

Как проходило исследование

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

Какие выводы

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

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

Исследование не позволяет сделать выводы о том, какие дополнительные элементы на скриншотах эффективны для направления визуального внимания пользователя, а
какие нет.

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

Краткое содержание. Август

- В Cloud Native Computing Foundation Community Awards 2021 включили номинацию Top Documentarian.

- Статья про то, должны ли технические писатели получать больше разработчиков.
Документация является неотъемлемой частью продукта, как и код. Поэтому работа технических писателей должна оплачиваться наравне с разработчиками. Согласно опросам, средние базовые зарплаты разработчика и технического писателя в США совпадают. Но это средние базовые зарплаты, у 25 % разработчиков зарплаты выше среднего, нет данных про такие же зарплаты для технических писателей. Статью обсуждали в Twitter и Slack.

- Статья Sarah Maddox про связь проклятия знания, синдрома самозванца и метазнания.
Если мы не понимаем, как много мы знаем и что это может кто-то не знать (проклятие знания), то можем думать, что другие люди знают намного больше нас и мы не заслуживаем достигнутого успеха или похвалы (синдром самозванца). Знание того, что мы знаем, — это метазнание. Прокачать свое метазнание можно через менторство или блог.

- Статья BBC про исследования UX-текстов. Часть 1 и часть 2.
В ней собраны различных тесты для текстов и метрики, на которые стоит обратить внимание, например: понимание текста и восприятие бренда, время, проведенное на странице, % пользователей, которые успешно или нет выполнили какое-то действие.

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

- Scott Kubie отвечает, обязательно ли быть носителем языка, чтобы преуспеть в качестве UX-писателя.
У неносителей языка есть преимущества при работе над контентом для международной аудитории или контентом, который необходимо будет перевести на несколько языков. Есть и недостатки, неноситель может допускать ошибки, но такое бывает и с носителями языка.

- Статья про то, что создателям контента не хватает термина для названия специальности.
В отрасли нет единого мнения по поводу названия ролей и отличий между ними. Примеры названия роли: Content strategy, Content design, UX writing, ContentOps, Content marketing, Content management, Content engineering, Digital communications, Technical communications, Web content creation, Conversation design.

Планы на сентябрь

- Митап Good vs. Bad API Documentation: How API Documentation Drives Service Adoption. Бесплатно, онлайн.

- Вебинар What does documentation quality really mean and how do we improve it?. Бесплатно, онлайн.

- Секция докладов про документацию на конференции React Finland. Бесплатно, онлайн.

- Воркшоп Docs-as-code: An AsciiDoc primer на конференции DevConf US 2021. Бесплатно, онлайн.

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

Хелп Infracost

Что David Nunez (менеджер документации из Stripe) и Stephanie Blotner (менеджер технических писателей из Uber) улучшили бы в хелпе Infracost, потому что они рассказали про это в видео.

🌟 Не хватает домашней страницы

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

🌟Говорите про результат

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

🌟Проводите исследования

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

🌟Больше исследований

Можно проводить пользовательские исследования еще до начала разработки фичи. Так делает Stripe. Создайте документацию, которая описывает процесс работы с будущей фичей, и протестируйте ее на пользователях.

🌟Сценарии использования

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

🌟Не пытайтесь описать все сразу

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

🌟Документация часть продукта

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

#хелплинч #makedocumentationgreat

​​Интерактивные инструкции Algolia

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

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

Другие примеры динамической документации для разработчиков можно подсмотреть у Stripe и Worldpay.

#makedocumentationgreat #developerexperience