Shut up and write

2021-08-20 14:00:10 Снова про скриншоты

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

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

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

Какие выводы

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

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

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

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

2021-08-13 14:00:18 Курт Воннегут о технических писателях

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

Цитата:
​​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. Пожалейте читателей. Открыть/Комментировать

2021-08-06 14:00:19 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, для тех кто пропустил.

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

2021-07-30 14:00:19 Краткое содержание. Июль

- Анонс 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. Бесплатно, онлайн.

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

2021-07-21 14:00:14 ​​Динамическая документация Worldpay

Документация для разработчиков движется от “вот ссылка на Swagger” к “вот пошаговая инструкция специально для тебя”.

У Worldpay в документации для разработчиков есть виджет “Tell us what you need”. В виджете нужно ответить, как вы планируете работать с API, например, кто будет аутентифицировать клиента. После ответов на вопросы вы получаете описание подходящего процесса: схему процесса работы и инструкцию, что нужно сделать по шагам.

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

2021-06-30 14:00:05 Краткое содержание. Июнь

- 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. Платно, онлайн.

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

2021-06-23 14:00:50 ​​Хелп Stripe

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

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

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

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

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

Видео

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

Навигация

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

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

2021-06-09 14:00:10 Менторство

Я начинала свою карьеру как единственный технический писатель в компании. Сама разбиралась, что нужно учить, чтобы расти в карьере. Когда я стала работать в команде, расти стало проще — помогал фидбэк и опыт коллег. Поэтому я считаю, что общение с ментором, который уже прошел похожий путь, сложно заменить. Про то, кто такой ментор, хорошо написано в канале 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
Для кого: для всех, есть технические писатели.
Бесплатно.

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

2021-06-02 14:00:54 Краткое содержание. Май

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

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

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

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

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

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

2021-05-14 14:00:24 ​​Devportal Awards 2021

В прошлом году я писала про премию «Devportal Awards», но с опозданием, подать заявку на участие было уже поздно.

В этом году публикую вовремя, подать заявку на участие можно до 30 июля. Номинаций стало больше, например, появились номинации «Лучший внутренний Devportal»
и «Лучшая модель монетизации».

Голосование за лучшие порталы начнется в сентябре.

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