Shut up and write
715 subscribers
42 photos
2 files
139 links
Я Маша и я технический писатель. Очень люблю документацию, особенно хорошую. Читаю все подряд: инструкции к стиральным машинам, правила пользования метро и справки разных сервисов.
На канале пишу о том, что понравилось или не понравилось.
@the_real_mari
Download Telegram
​​Хелп Ситимобил

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

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

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

Точность

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

Слова и фразы

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

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

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

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


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

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

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

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

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

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

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

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

❤️ Текст

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

❤️ Гифки

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

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

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

#хелплинч #makedocumentationgreat
​​Хелп Stripe

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

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

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

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

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

💜 Видео

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

💜 Навигация

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

#хелплинч #makedocumentationgreat
Хелп Infracost

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#хелплинч #makedocumentationgreat