​​Запоздалые новости

SpaceX запустили-таки ракету. Но как можно было сомневаться в тех, у кого посадочная площадка называется «Просто прочти инструкции».

​​Про Portal

А пока одни колонизируют Марс, я читаю документацию. Сегодня это документация к устройству для видеозвонков Portal. Чтобы его включить, нужно просто воткнуть вилку в розетку. Все очень просто, но в комплекте есть инструкция и в ней больше одного шага 😊

Зачем инструкция?

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

Еще раз про очевидные вещи

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

Третий шаг

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

Что дальше?

Но не все идеально, потому что в инструкции к устройству для видеозвонков нам не рассказали, как звонить. Наверное, потому, что дальше только ооочень простой интерфейс 😌
Конечно, это не вся инструкция, есть полная версия.

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

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

На Хабре вышла статья про то, как технический писатель снимает видеоролики.

Ну, вышла и вышла, что в этом такого

Технический писатель делает весь ролик сам: сам пишет сценарий, снимает, записывает звук, монтирует. Тратит на ролик примерно 80 часов, а в статье рассказывает подробности процесса.
А процесс у них построен так, что работа над роликом не останавливается, даже если согласующие в отпуске, заболели, уехали в командировку. Чтобы не затянуть создание ролика, замечания вносят не все, а только самые критичные.
И конечно, очень классно, что на Хабре появляются статьи про документацию, про то какой она может быть разной и классной!🖤

Про сценарии

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

Идеальный мир

Несколько лет назад я считала, что видеоролики в документации — это трата времени и денег, а смотреть их никто не будет, ведь можно все прочитать. Сейчас мое мнение изменилось. На это повлияли разные исследования про восприятие информации, собственный опыт создания роликов и общение с теми, кто их смотрит.
Я все еще считаю, что видеоролики стоят дорого, а обновить их быстро не получится. Но если вы можете их сделать, то делайте. Мир меняется, теперь видео есть везде:
- Google
- Яндекс
- Ozon
- Miro

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

У видео есть недостатки, которые не дают ему полностью заменить текст. Про цену повторяться не буду🤑
Для меня основные это:
- Сложно что-то найти, Ctrl+F не работает, пробежаться глазами тоже не получится. Сейчас на Youtube можно добавить в видео встроенный таймлайн, это помогает, но все равно не поиск.
- Долго смотреть, прочитать можно быстрее. Особенно если вы хотите повторить (перечитать) какой-то момент.
- Нужен быстрый интернет, без ограничений по объему трафика. С этим могут быть проблемы, например, в путешествии.
- А еще нужно не забыть наушники.

#точкароста #самсебережиссер

​​Boйс и тон оф войс. Часть 1

Сейчас почти каждый продукт пытается разговаривать с пользователем и желательно по-человечески. А еще при этом быть умными, но не занудными, милыми и веселыми, но не слишком. Но можно ли считать это «тон оф войс»? И будет ли это относиться к документации? Спойлер: Да, Да, Нет, Да.

Что такое голос и интонация?

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

Итого:
- Голос (voice) — постоянная величина, если вы решили, что вы разговариваете с пользователем по-человечески и не занудно, то громоздкие конструкции и сложные термины вы больше не используете.
- Интонация (tone of voice) — переменная величина, зависит от места и времени, но всегда соответствует вашему голосу. То есть вы можете шутить, а можете писать что-то серьезное, и все эти тексты не будут противоречить вашей интонации. Но громоздкие конструкции и сложные термины использовать нельзя все равно.
Достаточно сложно разделить голос и интонацию, это не всегда нужно и многие компании этого не делают.

Примеры голосов

Вот как описывают свои голос и интонацию разные компании:
- Mailchimp — откровенные, искренние, со сдержанным юмором.
- Monzo — разговаривают на языке своей аудитории, амбициозные, позитивные, открытые, инклюзивные.
- Atlassian — с твердой позицией, практичные, оптимистичные.
- Microsoft — теплые и спокойные, четкие и понятные, готовы протянуть руку помощи.
- Slack — уверенные в себе (но не дерзкие), остроумные (но не нелепые), в разговорном стиле (но всегда соответствующие и уважительные), интеллектуальные, дружелюбные (но не заискивающие), предупредительные (но не властные), ясные, лаконичные и человечные.
- Uber — внимательные, простые и постоянные, последовательные, а еще оптимистичные, гостеприимные.
- Skype — прямолинейные и человечные, с юмором.
- Bank of America — позитивные и оптимистичные, естественные и искренние, прямые и откровенные.

Сами описания длиннее, но мне все равно не помогло. Кажется, что у всех этих компаний очень много общего в описаниях, поэтому их сложно различить.

Викторина

Попробуйте угадать, какая из этих компаний могла написать такой текст:
A. Nоw that you've crеated the app dеscriptor, let's creаte the user interfаce using a simple static HTML page. This is the most bаsic type of XXX аpp, consisting only of аn аpp descriptor and an HTML page.
B. Fill оut yоur App Name and selеct the Develоpment Wоrkspace where you'll play around and build your app. Don't fuss too much over either field—no matter what worksрace you select, you'll still be able to distribute your app to other worksрaces if you сhoose.
C. Тар the Ноmе icon in the mеnu bаr, thеn scrоll to thе Pоt yоu wаnt tо clоsе
Тар thе Еdit button, then tap Dеlеtе Pоt in thе tор right оf thе scrееn
D. Sеarch bеcause it’s faster than scrоlling.

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

#тонофвойс

Nоw that you've crеated the app dеscriptor, let's creаte the user interfаce using a simple static HTML page. This is the most bаsic type of XXX аpp, consisting only of аn аpp descriptor and an HTML page.
anonymous poll

Microsoft – 8
👍👍👍👍👍👍👍 53%

Atlassian – 6
👍👍👍👍👍 40%

Slack – 1
👍 7%

Skype
▫️ 0%

👥 15 people voted so far. Poll closed.

Fill оut yоur App Name and selеct the Develоpment Wоrkspace where you'll play around and build your app. Don't fuss too much over either field—no matter what worksрace you select,you'll still be able to distribute your app to other worksрaces if you сhoose
anonymous poll

Slack – 7
👍👍👍👍👍👍👍 47%

Mailchimp – 7
👍👍👍👍👍👍👍 47%

Microsoft – 1
👍 7%

Uber
▫️ 0%

👥 15 people voted so far. Poll closed.

Тар the Ноmе iсоn in thе mеnu bаr, thеn scrоll to thе Pоt yоu wаnt tо clоsе Тар thе Еdit button, then tap Dеlеtе Pоt in thе tор right оf thе scrееn
anonymous poll

Monzo – 6
👍👍👍👍👍👍👍 55%

Bank of America – 3
👍👍👍👍 27%

Mailchimp – 1
👍 9%

Uber – 1
👍 9%

👥 11 people voted so far. Poll closed.

Sеarch bеcause it’s faster than scrоlling.
anonymous poll

Slack – 14
👍👍👍👍👍👍👍 78%

Atlassian – 2
👍 11%

Monzo – 2
👍 11%

Skype
▫️ 0%

👥 18 people voted so far. Poll closed.

Ответы

Та-дам, а вот и ответы, все как обещала.
1. Atlassian
2. Slack
3. Monzo, текст из хелпа мобильного приложения, но тут похожий
4. Slack, пример с канала lil words make magic

Boйс и тон оф войс. Часть 2

Часть 1

Кому нужен голос

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

Про правила

Я считаю, что невозможно написать универсальные и работающие правила для голоса и интонации в стиле такой-то компании. А общие формулировки типа «теплый, спокойный и уверенный в себе» выглядят как что-то невнятное. В них нет четкой формулы, так делай, а так нет. Способа проверки текста на соответствие выбранному тону еще нет. Что-то похожее есть, например, у Grammarly. Но у них ограниченный набор характеристик.
Я верю, что лучше всего работает команда людей, которая постоянно используют эти голос и интонацию, поправляют друг друга, делятся идеями. При этом можно зафиксировать важные общие принципы и приблизительные ограничения, перечислить сложные случаи и неоднозначные места. Собрать это все в одном документе и как-то его назвать.
Этот документ будет нужен не только внутреннего использования, а для того, чтобы объяснять, почему вы пишете так, а не иначе, такой юридический документ для текстов, аналогично стайлгайду.

Про уникальность

Для меня может быть два варианта голоса:
- серый — не хочет выделяться, просто какой-то голос в толпе
- яркий — хочет отличаться от остальных
Подходы по созданию голоса тут будут разные. В первом случае можно скопировать правила русского языка/Ильяхова/чужой голос, во втором придется включить фантазию. При этом странно называть скопированные правила своим голосом, потому что в нем нет уникальности.
Не страшно копировать у других компаний, если вам это подходит. Например, можно начать использовать смайлики как Slack. Главное вовремя остановиться, потому что весь прикол голоса в том, что он чем-то отличается от других. Все уже пишут понятно, пытаются шутить, но голос не только про это.
Пример отличительного голоса — это Ikea. Его не спутать, можно создать документацию в их стиле даже без описания. При этом свой голос они описывают одним абзацем. И там нет ничего про схематичные картинки.

Другие мнения

Другие не потому, что противоположные, а потому, что не мои.
- Видео Tone in Documentation. Показывает примеры расхождения интонации в интерфейсе и документации, в документации и жизни. Это доклад 2014 года, поэтому примеры могли устареть.
- Статья Let’s Talk About Brand Personality, Voice, and Tone. Серьезная маркетинговая статья, тут и ссылки на научные исследования, и архетипы Карла Юнга. Если бы я сейчас писала по этой теме диплом, то взяла бы отсюда половину.
- Видео про голос бренда. Похоже на статью выше, только короче и видео.
- Статья How I crafted the new voice and tone to a product: clarifying values and attributes. Пример живого UX-писателя, который создал голос компании с нуля. В последней статье (их всего 3) есть описание и разделы получившегося гайда по голосу.
- Статья Nielsen Norman Group The Four Dimensions of Tone of Voice. Это прям 🍒🍒🍒, если вы еще не читали, то надо. Во-первых, они выделили 4 (всего лишь) характеристики интонации. Во-вторых, показали на примере, как это работает. В-третьих, проверили, что пользователи замечают изменения в интонации.

#тонофвойс

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

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