"Shut up and write" Телеграмм канал

"Shut up and write" Телеграмм канал

Адрес канала: @shut_up_and_write
Категории: Технологии
Язык: Русский
Страна: Россия
Количество подписчиков: 503 (Дата обновления: 2021-02-02)
Описание канала:

Я Маша и я технический писатель. Очень люблю документацию, особенно хорошую. Читаю все подряд: инструкции к стиральным машинам, правила пользования метро и справки разных сервисов.
На канале пишу о том, что понравилось или не понравилось.
@SmirnovaMariia

Переходов в канал: 0 ( 87 )

Последние сообщения

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

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

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

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

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

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

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

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

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

В следующий раз расскажу про требования к фидбеку, который дают судьи.
181 viewsShut_up_and_write_bot
Открыть/Комментировать
2021-01-29 15:00:36 Про судейство на Technical Communication Competitions

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

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

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

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

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

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

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

- Организация информации. Насколько отчетливо видна структура? Насколько она логична и последовательна? Разделен ли текст на подразделы или темы с понятными по заголовкам и подзаголовкам?
- Объем содержания. Насколько подходит объем материала для аудитории и цели?
Есть ли в документе вся необходимая информация?
- Навигация. Насколько легко пользователь может найти информацию? Насколько хорошо навигация помогает пользователю? Насколько интуитивно понятен интерфейс навигации? Правильно ли работают ссылки, кнопки и закладки? Сводит ли дизайн к минимуму необходимость прокрутки?
- Оглавление. Насколько точно и последовательно оглавление? Насколько хорошо верхние и нижние колонтитулы поддерживают информационную иерархию? Если оглавления нет, то нужно ли оно?
- Перекрестные ссылки. Перекрестные ссылки ведут на нужную страницу? Насколько хорошо текст перекрестной ссылки описывает целевую информацию? Если перекрестных ссылок нет, то нужны ли они?
- Индекс. Насколько хорошо построен и развит индекс? Предоставляет ли индекс альтернативные способы поиска материала, используя перекрестные ссылки и синонимы? Если индекса нет, то нужен ли он?
- Поиск (только электронные работы). Насколько интуитивно понятна работа поиска? Влияют ли регистр, опечатки и вариации слов на результаты поиска? Если поиска нет, то нужен ли он?
170 viewsShut_up_and_write_bot
Открыть/Комментировать
2021-01-22 15:00:31 Про судейство на Technical Communication Competitions

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

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

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

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

Категории

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

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

Подавая заявку на участие в соревновании, конкурсанты выбирают одну из категорий, рассказывают для кого предназначен этот материал и каких целей хотели достичь. Информация из заявки видна судьям.
Каждый судья оценивает работу по определенным критериям, фактически отвечает на вопросы форме. После заполнения форм судьи собираются вместе и обсуждают свои оценки. В итоге судьи должны прийти к общему мнению.
В судьи берут людей с разным опытом и стажем работы. Для меня было удивительно, что в команде, в которой была я, оценки совпали на 85 процентов, а там где не совпали, мы быстро договорились. На мой взгляд, в этом помогли четкие критерии оценки. Вот про них напишу подробнее в следующий раз.
Чтобы стать судьей можно подать заявку в одно из отделений STC. Обычно все встречи судей проходили офлайн, поэтому участвовали те, кто мог присутствовать лично. В 2020 все было онлайн, поэтому на локацию не обращали внимания. В 2021 скорее всего будет так же.
Picture 100 from Shut up and write 2021-01-22 15:00:31
259 viewsShut_up_and_write_bot, edited  
Открыть/Комментировать
2021-01-15 15:00:36 Лучшие примеры технической коммуникации

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

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

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

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

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

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

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

#makedocumentationgreat
Picture 100 from Shut up and write 2021-01-15 15:00:36
357 viewsShut_up_and_write_bot
Открыть/Комментировать
2021-01-08 15:00:10 Как пользователи воспринимают контент

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

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

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

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


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


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


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


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

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

#экспериментыналюдях
Picture 100 from Shut up and write 2021-01-08 15:00:10
388 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-12-18 15:00:38 ​​Инструкции совсем как у Икея

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

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

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

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

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

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

#tools
441 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-12-04 15:01:01 Краткое содержание. Ноябрь

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

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

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

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

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

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

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


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

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

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

#полезныессылки
Picture 100 from Shut up and write 2020-12-04 15:01:01
488 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-11-27 15:00:36 ​​Developer experience

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

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

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

Метрики

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

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

#экспериментыналюдях
413 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-11-20 15:00:26 ​​Хелп Miro

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

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

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

❤️ Текст

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

❤️ Гифки

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

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

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

#хелплинч #makedocumentationgreat
Picture 100 from Shut up and write 2020-11-20 15:00:26
489 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-11-06 14:00:21 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 в виде пуллреквеста.


#тулзы
Picture 100 from Shut up and write 2020-11-06 14:00:21
471 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-10-23 14:00:52 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).

#вестникмитапов
Picture 100 from Shut up and write 2020-10-23 14:00:52
459 viewsShut_up_and_write_bot, edited  
Открыть/Комментировать
2020-10-16 15:00:30 Red Hat Documentation

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

Что там есть:

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

#гайд
Picture 100 from Shut up and write 2020-10-16 15:00:30
524 viewsShut_up_and_write_bot
Открыть/Комментировать
2020-10-12 14:01:04 UPD Random Coffee

Я отправила всем участникам Random Coffee сообщения в телеграмм с именем их партнера. Дальше они сами знают, что делать 😊
Новый раунд сделаю через две недели, оповещение будет на канале. Идеи можно писать в комменты или мне в личку.
514 viewsShut_up_and_write_bot, edited  
Открыть/Комментировать