Примеры руководства пользователей по сайту

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

Приятного чтения.

Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:

1. Качественная документация повышает лояльность клиента и ценность продукта в целом.

Как это не странно, но люди до сих пор читают пользовательскую документацию. Конечно, не просто так, а когда сталкиваются с проблемой. И если с руководством все хорошо, то пользователь быстро найдет ответ на свой вопрос – это будет ещё один балл в копилку вашего проекта!

2. Руководство пользователя экономит время и силы техподдержки.

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

А теперь к советам!

Общие советы по созданию руководства пользователя

Прежде чем начинать писать руководство пользователя нужно ответить на несколько вопросов. — Для кого вы пишите? Кто будет пользоваться файлом справки? (ваша целевая аудитория)

— Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)

— Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?

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

(Для изложения лучше всего выбрать нейтрально-формальный стиль)

Структура руководства пользователя

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

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

В первом разделе расскажите общую информацию о продукте. Для чего создан проект и какие задачи он решает.

Во второй «главе» укажите основные элементы интерфейса. Клиент вряд ли сможет достичь своей цели в программе, если не будет знать для чего служат различные детали интерфейса. Объясните предназначение всех окон, кнопок и так далее.

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

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

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

И последний «обязательный» раздел, которой точно должен быть в любой документации – «контактная информация». Данный раздел даст пользователю возможность связаться с разработчиком. Если руководство вдруг не закрывает потребность читателя, то он может обратиться в поддержку. Кроме того, клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.

Профессиональный совет: если вы хотите максимально облегчить ношу клиента при чтении документации создайте контекстно-зависимую справку. Что это такое?

Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»

Как ее сделать? Смотрите ниже.

Контент

И так, мы создали «каркас» нашей документации, но чтобы руководство стало полезным нужно наполнить её компетентной информацией.

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

1. Понятность.

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

2. Наглядность.

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

3. Видео.

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

Но как добавить в документацию видео? Смотрите ниже.

Больше советов!

Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.

Создайте файл справки и загрузите его прямо в вашу программу в формате CHM. Таким образом, у пользователя будет возможность открыть документ, не выходя из программы. Не забудьте добавить элемент вызывающий руководство в меню программы.

Выложите руководство на сайт в формате HTML, чтобы клиент мог обратиться к документации, даже не работая с программой. Кроме того, документация, выложенная на сайт, повышает SEO факторы сайта.

И напоследок, переведите пользовательскую документацию в формат PDF, чтобы клиенты могли скачать и распечатать руководство.

Но помните, что после публикации документации, придется иногда её обновлять.

Инструменты

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

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

Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.

Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.

В программе есть шаблоны документации, ведь по образцу работать проще.

Импортируйте в программу заранее написанные фрагменты документации.

Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!

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

Если вы хотите создать по-настоящему хорошую документацию – придется потрудиться, потому что это займет много времени и усилий всей команды. Но игра стоит свеч, так как после этого вы получите лояльных и довольных клиентов.

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

Работая с Dr.Explain, можно быстро написать пользовательскую документацию, которая будет помогать клиентам разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.

Спасибо за внимание!

Со всеми возможностями Dr.Explain можно ознакомиться здесь:

Инструкция для пользователей сайта

преподавателя Кропачевой Т.Е.

Интернет-сайт создан для людей, чья деятельность связана с педагогикой и преподаванием и для тех, кому интересна эта тема.

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

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

Для пользователей и посетителей сайта

Если вы желаете ознакомиться с содержимым нашего сайта, то для удобства, вам нужно знать его структуру и интерфейс.

Так как сайт предназначен, прежде всего, для размещения и получения информации об учебной и внеклассной деятельности преподавателя Кропачевой Т.Е., для общения пользователей (педагогов, студентов и их родителей) между собой, для демонстрации опыта педагогов, то естественно, управление просмотром вынесено на самое видное место.

Вверху главной страницы, вы можете видеть навигационную ленту. Она содержит основные тематические разделы сайта: Просмотр, Гостевая, Аудио, Видео. В ней отображаются основные вкладки на сайте. Кликнув ЛКМ по вкладке Ленты, вы можете открыть вкладку.

Слева главной страницы представлена краткая информация о преподавателе: профессия, профессиональные интересы, увлечения, место работы и др.

Также слева расположена панель Навигация по сайту (Рис. 1), на которой расположены основные страницы мини – сайта преподавателя.

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

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

Рис. 1 Панель Навигация

История сайта и традиции

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

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

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

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

Правила общения на сайте

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

Если вы будете вежливы, просты в общении, внимательны к собеседникам, народ к вам потянется… Если начнете хамить, провоцировать, плести интриги, с вами никто не захочет общаться.

Запреты

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

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

1. Запрещается употреблять ненормативную лексику.

2. Запрещается прибегать к откровенным оскорблениям личности собеседника.

3. Запрещается создавать темы с неинформативными названиями, например «Помогите», «Ух ты!» или «Хочу спросить».

4. Запрещается создавать темы в непрофильных разделах или дублировать темы в разных разделах.

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

6. Запрещается обсуждение и тем более осуждение действий администрации форума в открытых разделах.

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

8. Запрещается использование символики Третьего Рейха в аватарах, т.к. это может расцениваться пропагандой идей фашизма.

Будьте, пожалуйста, вежливы и обходительны с вашими собеседниками. Хамов нигде не любят и не терпят.

1. Инструкция для пользователя

1. Минимальный
   заказ в интернет-магазине – 300 рублей.

2. Выбрать
   понравившийся товар путем нажатия на
   кнопку «ДОБАВИТЬ В КОРЗИНУ». В окошке
   «КОЛИЧЕСТВО» указать количество
   одноименного товара, которого вы хотите
   приобрести.

3. При
   нажатии на кнопку «ДОБАВИТЬ В КОРЗИНУ»
   вы будете каждый раз оказываться в
   «КОРЗИНЕ ЗАКАЗОВ».

4. При
   нажатии на кнопку «ОФОРМИТЬ ЗАКАЗ» Вы
   попадаете на страницу авторизации.

5. Вы
   уже зарегистрированы – нужно ввести
   «ИМЯ ПОЛЬЗОВАТЕЛЯ» и «ПАРОЛЬ». Если
   вы в первые на сайте, то вам необходимо
   ввести данные указанные в анкете,
   поставить галочку «Я согласен с данными
   условиями» и нажать кнопку «РЕГИСТРАЦИЯ».
   После этого на вашу почту придет письмо
   с вашим «ИМЕНЕМ ПОЛЬЗОВАТЕЛЯ» и
   «ПАРОЛЕМ», которые вам пригодятся для
   авторизации в интернет-магазине.

6. Далее
   вам необходимо авторизироваться на
   сайте, используя для этого «ИМЯ
   ПОЛЬЗОВАТЕЛЯ» и «ПАРОЛЬ», которые
   пришли к вам на почту.

7. Нажать
   на кнопку «ПОКАЗАТЬ КОРЗИНУ» в верхнем
   правом углу сайта.

8. Нажать
   кнопку «ОФОРМИТЬ ЗАКАЗ»

9. Далее
   Вам необходимо подтвердить адрес
   доставки или указать новый адрес.
   Нажать кнопку «ДАЛЕЕ».

10. Выбрать
    соответствующий вариант доставки.
    Нажать кнопку «ДАЛЕЕ».

11. Выбрать
    способ оплаты. Нажать кнопку «ДАЛЕЕ».

12. Нажать
    на кнопку «ПОДТВЕРДИТЬ ЗАКАЗ», при
    желании можно оставить комментарии в
    соответствующем поле.

13. В
    случае возникновения затруднений, Вы
    можете обратиться к «Онлайн консультанту»
    или заполнить форму «Обратной» связи.

1. Инструкция для администратора

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

Авторизация

Прописав
в адресной строке адрес своего сайта,
добавив в конце administrator, вы заходите на
страницу авторизации, после ввода
логина и пароля вы переходите в панель
управления.

Рисунок
57 — Вход

Вводная
информация и термины joomla

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

Рисунок
58 — Админпанель

Значки
панели управления

Рисунок
59 — Значки

1. Создание
   материала — одним из основных элементов
   в Joomla является статья (или материал).
   Этот пункт меню позволяет перейти к
   созданию новой статьи.

Рисунок
60 — Добавить материал

1. Все
   материалы — менеджер материалов, в
   который Вы попадете щелкнув по «Все
   материалы», позволяет Вам выполнять
   все необходимые действия с уже
   существующими статьями, быстро создать
   новую статью, изменить параметры
   отображения для всех статей и многое
   другое.

Рисунок
61 — Все материалы

1. Менеджер
   категорий — все материалы (статьи) в
   Joomla хранятся в определенных разделах
   и категориях. Это позволяет сортировать
   статьи в определенном порядке и
   облегчить доступ к любому материалу.

Рисунок
62 — Категории

1. Медиа
   менеджер — это один из бесполезных
   элементов административной панели
   Joomla. Основное его назначение — удаление
   лишних изображений, загруженных на
   сервер.

Рисунок
63 — Медиа

1. Менеджер
   Меню — один из главных элементов для
   любого сайта, а в случае с Joomla его
   важность возрастает в разы. Именно с
   помощью меню настраивается отображение
   тех или иных модулей на странице, формат
   вывода материалов и прочее.

Рисунок
64 — Все меню

1. Менеджер
   пользователей – это элемент предназначен
   для управления учетными записями
   пользователей: создание, удаление,
   изменение.

Рисунок
65 — Менеджер пользователей

1. Менеджер
   модулей — в этом разделе собраны все
   дополнения к вашему сайту.

Рисунок
66 — Менеджер модулей

1. Менеджер
   расширений — в этом разделе вы можете
   загрузить на сайт дополнительный
   функционал.

Рисунок
67 — Установка

1. Менеджер
   языков — присутствует разделение в
   менеджере языков на административную
   и лицевую панели. Можно выбрать любой
   установленный язык.

Рисунок
68 — Языки

1. Общие
   настройки — имеются достаточно много
   общесистемных настроек, влияющих,
   непосредственно на функционирование
   сайта под управлением Joomla.

Рисунок
69 — Общие настройки

1. Менеджер
   шаблонов — в этой категории вы можете
   выбрать шаблон для своего сайта или
   загрузить и установить свой.

Рисунок
70 — Менеджер шаблонов

1. Мой
   профиль или другими словами личный
   кабинет.

Рисунок
71 — Мой профиль

Вводная
часть virtuemart

Добавление
категорий, товара, описания, производителей
осуществляет через панель управления
Virtuemart.

Рисунок
72 — Панель управления virtuemart

Добавление
и редактирование товара

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

Рисунок
73 — Создание категории

• В
  форме присутствуют следующие поля:

• основные
  настройки;

• название
  категории – без комментариев;

• опубликовано
  – будет ли категория опубликована на
  сайте, либо пока скрыта;

• псевдоним
  – то, как будет выглядеть текст категории
  в ссылке URL. (Например:
  wedal.ru/shop/moloko/prostokvasheno.
  Если не указывать ничего, то поле после
  сохранения автоматически заполнится
  транслитом названия категории.);

• описание
  – описание категории. Оформляется в
  редакторе, а значит может содержать
  форматирование.

• подробнее:

• порядок
  – порядок расположения категории в
  списке категорий;

• родительская
  категория – если категории имеют
  некоторый уровень вложенности, то
  здесь можно выбрать родительскую
  категорию для создаваемой, при условии,
  что она существует;

• товаров
  в строке по умолчанию – аналог шаблонам
  browse_xиз Virtuemart. Позволяет выбрать, сколько
  колонок с товарами будет в категории;

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

Для
добавления товара переходим в товары
и нажимает кнопку «Создать».

Форма
добавления товара достаточно большая
и разбита на несколько вкладок. Рассмотрим
каждую из них отдельно.

• вкладка
  «Информация» — эта вкладка содержит
  основную информацию о товаре;

Рисунок
74 — Информация

• вкладка
  «Описание» — эта вкладка содержит
  краткое и подробное описания товара,
  а также мета-данные;

• вкладка
  «Статус» — эта вкладка содержит данные
  о количестве товара;

Рисунок
75 — Статус

• вкладка
  «Габариты / Вес» — эта вкладка содержит
  описание размеров товара, веса, и.т.п;

Рисунок
76 — Габариты

• вкладка
  «Изображения» — на этой вкладке к товару
  добавляется основное изображение;

• вкладка
  «Настраиваемые поля» — на этой вкладке
  к товару добавляются сопутствующие
  товары и категории, в также дополнительные
  поля.

Рисунок
77 — Настраиваемые поля

Существует
два вида добавления изображения для
товара:

1. Способ.
   Загрузка через форму добавления.

В
нижней части формы товара во вкладке
изображения существует форма выбора
файла.

Рисунок
78 — Загрузка файла

1. Способ.
   Ручная загрузка на сервер и выбор из
   списка загруженного.

Вы
можете загрузить все изображения на
сервер разом в папку, указанную в нижней
части формы. После этого В поле «Поиск
Изображения» поставьте пробел / Нажмите
кнопку «+16» / начните писать название
изображения и во всплывающем окне
появятся изображения, имеющиеся в папке
на сервере, из которых можно выбрать
то, которое необходимо для товара.

Рисунок
79 — Ручная загрузка

Товар
который вы добавите будет выведен на
складе автоматически, вам остается
ввести количество.

Рисунок
80 — Склад

Создаем
список производителей

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

Рисунок
81 — Описание

Заполняем
название производителя, описание и
изображение.

Рисунок
82 — Изображение

После
того как все данные будут заполнены
список пользователей будет выглядеть
так.

Рисунок
83 — Список

Настройки

1. Настройки
   — Самый большой раздел с общими
   глобальными настройками интернет
   магазина, состоящий из семи вкладок
   (Магазин, Внешний вид, Шаблоны,
   Формирование цен, Оформление заказа,
   Настройки заказа, SEO).

Рисунок
84 — Настройки

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

Рисунок
85 — Заполняемые поля

1. Статусы
   заказов — состояние заказанного товара
   в базе данных интернет магазина: Pending
   — Ожидаемый, Confirmed — Подтвержденный,
   Cancelled — Отмененный, Refunded — Оплаченный,
   Shipped — Отправленный покупателю.
   Администратор магазина может расширить
   список статусов заказов интернет
   магазина.

Рисунок
86 — Статусы заказов

заключение

В
ходе выполнения дипломного проекта
была достигнута основная цель работы
– разработан и создан полноценный
Интернет-магазин «Черемушки».

Все
поставленные задачи были выполнены в
полном объеме:

• изучение
  интернет-магазинов и выявление их
  недостатков;

• обоснование
  необходимости создания интернет-магазина;

• проведение
  анализа и выбор интернет-технологий
  для разработки интернет-магазина;

• разработка
  динамических web-страниц интернет-магазина,
  управляемых базой данных;

• оценка
  эффективности выполненной разработки.

В
данном проекте для разработки и создания
сайта был выбран язык программирования
php.

PHP
– это скриптовый server-side язык
программирования, предназначенный в
основном для включения в html страницу
и выполняемый сервером перед выдачей
страницы браузеру.

HTML
(HyperText Markup Language) является стандартным
языком, предназначенным для создания
гипертекстовых документов в среде WEB.
HTML-документы могут просматриваться
различными типами WEB-браузеров.

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

Благодаря
результатам испытаний интернет-магазин
«Черемушки» можно заявить что — это
полноценный реализованный продуктовый
магазин в интернете.

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

На
сайте весь товар разбит на восемь
больших категорий, далее он перетекает
в подкатегории где покупатель с
легкостью найдет нужный ему товар –
каждый товар имеет подробное описание
с изображением, и показано сколько
товара осталось на складе. Также на
сайте приведен и показан рекомендуемый
товар и акции, либо если это новый
посетитель сайта, покупатель может
воспользоваться поисковой лентой и
отдельными вкладками «Как заказать»
и «Доставка и оплата».

Система
управления php-скрипта открывает широкие
возможности и перспективы интернет-магазину
«Черемушки», позволяя ему изменяться
в ногу со временем, развиваясь, расширяясь
и совершенствуясь.

Четко
и грамотно — подготовленная информация
позволяет покупателю найти нужный ему
товар за довольно короткий срок времени.

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

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

Соседние файлы в предмете [НЕСОРТИРОВАННОЕ]

• #
• #
• #
• #
• #
• #
• #
• #
• #
• #
• #

Туториал для туториалов. Как написать пользовательскую документацию

Есть устоявшеёся мнение, что для хороших продуктов руководство пользователя не нужно. Очередной холивар на эту тему разгорелся в нашем рабочем чате. Я не до конца согласен с этим утверждением. 

Хороший интерфейс действительно должен помогать пользователю быстро понять продукт и научиться им пользоваться. Как всегда есть пара НО. 

• Пользователи бывают разные. То есть они могут отличаться как по возрасту, отрасли и опыту, так и по количеству мотивации. Мотивация особенно касается b2b сервисов. Многие пользователи попадают в продукты, потому что «Начальник сказал».

• Продукты бывают сложные. Быстро разобраться и понять все их фишки без документации сложно или невозможно.

Документация помогает пользователю решить проблему или помочь разобраться с особенностями и фишками продукта. В любой документации люблю раздел Tips&Tricks.

Что входит в пользовательскую документацию

Пользовательская документация — это не юридические документы. У них другие цели.

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

Что еще можно отнести к пользовательской документации

Документация для разработчиков и администрированию: доки по API, инструкции по установке и администрированию. Но сейчас их касаться не буду.

В пользовательскую документацию я включаю:

• Ответы на часто задаваемые вопросы (FAQ).

• Руководство пользователя. Это самый жирный кусок из всей пользовательской документации. Здесь описывается весь интерфейс, только текстом.

• Краткое руководство пользователя. Короткая презентация или документ для быстрого начала. Описывает базовые функции, возможности и советы для начала. Главное отличие от полного руководства — быстрее читаются, дают базовое представление о продукте и особенно помогают при внедрении b2b продуктов.

• Описание отдельных фишек (Tips&Tricks). Чаще всего их делают в формате видеоуроков, но можно наткнуться и на текстовые.

• Релизноуты. Считаю их важной частью пользовательской документации. И, говоря релизноуты, я имею ввиду не разовые, которые выкладываются в магазины приложений или к себе на сайт. А написанные раз в какой-то период. Можно раз в месяц. При работе над прошлым продуктом мы писали всё, что исправили или добавили за месяц. Хорошим тоном, на мой взгляд, будет писать самое важное. 

• Видеоуроки. Считаю их частью пользовательской документации, но это скорее вкусовщина, чем правило.

Почему это важно?

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

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

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

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

Красоты B2B рынка

Прошлый продукт, над которым мы с командой работали, умел и в облако, и в on-premise.
С облаком все понятно. Динамическая документация на сайте или в другом сервисе. Документация для корпоративных заказчиков имеет определенные особенности. 

Особенность #1: Корпорации любят печатную документацию. Очень сильно.
Мой знакомый сейлз любит рассказывать истории про это. 

Резюме его историй:

Если вдруг что, отчитываться о покупке, установке и эксплуатации корпорации будут большими стопками документации.

Поэтому чем толще кипа бумаги — тем лучше.

Особенность #2: Нужно отдавать дополнительные пакеты документов.
В дополнительные пакеты документов входит: документация по установке вашего ПО и документацию по его администрированию, а может ещё что-то, если попросят.

Особенность #3: Документацию, которую вы отдаете корпоративному заказчику, нужно будет поддерживать отдельно. 
Реальность работы с большими корпоративными заказчиками в том, что ваш продукт требует доработки для решения их задач. Всегда есть какие-то нюансы и дополнения. Поэтому отдавать им облачную документацию, чаще всего, не получится.

Особенность #4: Встречается реже, но тоже требует внимания. Если ваш продукт визуально кастомизируется (меняются цвета, меняется расположение кнопок), то для каждого заказчика с нестандартным интерфейсом нужно будет делать свою документацию. Это не правило, а скорее хороший тон и забота.

Где делать?

Много думал, долго смотрел. Переделывал наш гайд раз пять.

Когда искал, ставил для себя следующие задачи:

• Документацию можно сделать динамической. То есть возможность грузить видео, гифки, делать кросс-ссылки.

• Поддерживается базовое форматирование: заголовки, жирный, курсив, code, code block.

• Возможность экспортировать в .pdf.

Небольшой совет

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

• Есть возможность выложить документацию на свой домен.

• Есть возможность кастомизации для заказчиков. Поменять цвета, добавить логотипы и прочее.

Какие вариант рассматривал:

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

• Google Docs.
  Стоимость: Free
  Плюсы: очень удобно работать с вёрсткой документа; привычный, при этом более простой интерфейс, относительно MS Docs; есть синхронизация с облаком; есть экспорт в .pdf.
  Минусы: очень тяжело работать с визуальной частью — скринами; отношу в категорию не динамичных, так как выложить ссылочку на сайт на Google Doc конечно можно, особенно учитывая их последние апдейты, но это выглядит как-то не серьезно. 

• Notion.
  Стоимость: можно Free, если работает один человек, а так от 8-10$ за человека.
  Плюсы: очень удобно делать динамическую документацию, которую не стыдно выложить на сайт, по моим ощущениям; удобно работать в паре, есть все необходимое; можно вставить любое медиа, хоть ссылку, хоть видео, хоть схему из miro.
  Минусы: не самый широкий спектр инструментов для работы с версткой; если неправильно сверстать, скопировать кусочек текста в другое место бывает накладно; не для всех пользователей привычная навигация по страницам.

• Другие инструменты для wiki. Я смотрел на несколько вариантов wiki.js, Stonly 2, Dropbox Paper, Outline. 

  Смотрел давно, поэтому ничего вразумительно сказать не смогу. Помню, только что из всего выше, зацепил Dropbox и Wiki.js. В процессе написания этой статьи наткнулся ещё на один интересный сервис — GitBook. Он удовлетворяет всем моим запросам к подобным инструментам, но прошел мимо меня когда выбирал. 

• Figma.
  Не пробовал, но хочу попробовать для ускорения работы именно с корпоративной документацией, есть у меня одна идея, как будет время попробую и расскажу.

С чего начать?

Не скажу ничего нового.
Начинать нужно с ответа на вопрос «Зачем мы это будем делать?». Мы начинали писать первую версию как раз для корпоративного заказчика. Но эта итерация была небольшой. Писали краткий гайд.

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

После того, как поняли зачем, накидайте план, а точнеё оглавление. План подразумевает последовательность, а оглавление позволяет вам писать не последовательно. Я писал непоследовательно. Сначала писал то, что помнил на память, потом все остальное.

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

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

Основные правила

Понятный и простой язык

Я не буду писать о важности соблюдения правил русского языка: орфографии, пунктуации. И не буду рассказывать «Как писать хорошо?». Я сам далеко не эксперт в этом вопросе, поэтому когда мне нужно написать хороший текст я всегда обращаюсь к заветам Ильяхова и сервисам Главред, Яндекс.Спеллер и LanguageTools.

Любой текст должен быть простым и понятным.

Самое главное всегда это помнить.

Из рекомендаций, которые могу дать я лично — отказываться от привычных определений и писать ещё проще. 
Например, вместо «Кликнуть» писать «Нажмите», вместо «Свайпнуть» — «Провести». Так нужно делать, потому что среди пользователей могут быть люди, которые не знают даже базовых терминов. 

Понятное и аккуратное форматирование

Я люблю типографику и когда все аккуратно. Поэтому случаются приступы гнева, когда документы плохо сверстаны. Считаю это важным, так как эти правила придумали не просто так, а чтобы было удобно для читателя. 

Правил много. Расскажу про самые бесячие и самые важные, на мой взгляд:

• Кавычки.
  Все то ли ленятся, то ли не знают где на клавиатуре находятся наши кавычки. У меня есть предположение, что эта привычка пошла со школ, потому что руками мы пишем другие кавычки. 

  Основные кавычки оформляются елочкой «», внутренние кавычки оформляются лапками „“. Например, «Нажмите на вкладку „Контакты“ в левом верхнем углу», забугорные кавычки выглядят так «_».

  

  P.S. Иностранные названия в русском тексте кавычками не выделяются. 

• Тире и дефис.
  Все знают про тире и дефис. Оказалось, что многие не знают про среднее тире.

  Дефис (-) используется для присоединения частиц (что-то), для присоединения префиксов (по-братски), в словосочетаниях и сложносоставных словах (бизнес-ланч).
  Среднее тире (–) применяется в числовом обозначении диапазонов и интервалов: 2011–2022, 11–12 ноября.
  Длинное тире (—) используется для выделения прямой речи, указания маршрутов (Москва — Санкт-Петербург), между подлежащим и сказуемым.

• Оформление списков.
  Существуют два вида списков: нумерованный и маркированный.

  Маркированные списки выделятся буллитами, длинным тире или выключкой (реже всего встречается, сдвиг вправо, без символа), нумерованные списки выделяются числами.

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

  Нумерованный список используется когда есть четкая последовательность пунктов. Когда последовательности нет — всегда маркированный.

  Ещё один важный момент. 

  • Если пункт списка начинается с большой буквы, на конце всегда точка.

  • Если пункт списка один или два слова и начинается с маленькой буквы, на конце запятая, в конце списка точка.

  • Если пункт списка длинный и внутри пункта есть запятые, на конце ставим точку с запятой.

• Оформление дат и чисел.
  Если в тексте присутствуют даты, то лучше писать 15 мая 2021, а не 15.05.2021. Помогите пользователю думать только о важном.

  Если есть числа, то их нужно тоже оформить правильно. Не 2221, а 2 221. Отделяйте тысячные, это очень сильно упрощает восприятие.

• Вы или вы.
  Мое стойкое мнение — если это не коммуникация с кем-то из государственной организации в переписке, всегда писать вы и ваш с маленькой буквы. Иначе выглядит, что вы кричите на пользователя, а на пользователя нельзя кричать. 

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

• Буква Ё.
  С этой буквой у меня особые отношения. Исторически моя фамилия пишется через Ё, но из-за передергивания правил русского языка в советском союзе моя фамилия теперь пишется через Е. Поэтому я долгое время принципиально везде писал Е. Годы идут. Мозгов прибавилось. Теперь стараюсь писать Ё везде, где ей место. Так действительно проще воспринимать текст.

• Эмодзи в тексте 🦄
  По этому поводу много споров как у нас в команде, так и в кругах пишущих. Я придерживаюсь мнения, что эмодзи в тексте допустимы, но очень дозировано.

  Я использовал эмодзи для визуального подчеркивания каких-то кнопок в интерфейсе.
  Например: Нажмите на символ ⚙️ в правом верхнем углу.

  Для поиска символов пользуюсь Glyphy.

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

Если ваш продукт международный

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

Удобная навигация

Нет единого мнения — как правильно. Если самопис, я рекомендую делать вертикальную навигацию слева. Такая часто встречается в технических документациях.

По структуре, на мой взгляд, можно выделить такие блоки:

• Блок общего и важного.

  • Описание вашего решения. Вдруг пользователь попал сначала на ваш гайд, а не на сайт.

  • FAQ.

  • Какие есть приложения, со ссылками на скачивания или как пользоваться, если это например веб-версия.

  • Наши обновления.

• Блок «Как начать». Сюда писать общие вещи, которые касаются всего сервиса. Особенно важный блок, если у вас мультиплатформенное решение.

• Блок с руководством пользователя. Если у вас мультиплатформенное решение, то на каждую платформу лучше писать свое руководство. Можно объединять мобильные приложения и ПК версию. Так можно делать если нет глобальной разницы.

  У нас, например, исторически разницы не было. Поэтому iOS и Android лежат на странице «Мобильные приложения». Но сейчас мы начали разделять, поэтому в будущем будет разделение на ОС.

Связность

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

Если хочется сделать по красоте, то можно внимательно изучить методологию Zettelkasten, например.

Удобный поиск

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

Вот как мы это в Notion решили.

Логичность

Всё, что вы пишите должно быть логичным. 

Порядок элементов в тексте и интерфейсе должен быть одинаковым. Пользователь ломается, когда написано: «Нажмите на вторую вкладку „Контакты“», а вторая вкладка — «Чаты». 
Или когда в интерфейсе элемент называется «Назначить админом», а написано «Назначить администратором». 

Понятная визуалка

Этот пункт я бы хотел разбить на два блока: работа с медиа и работа с Step-by-Step.

Работа с медиа

Я сторонник динамичных гайдов. Когда есть .gif или видео презентация. Это помогает увидеть наглядно. Если есть возможность, наполняйте вашу документацию .gif.
С видео все сложнее. Оно требует дополнительного действия от пользователя — включить, плюс весит больше чем .gif. Поэтому видео использую редко. Чаще для каких-то больших блоков или полноценных видеоуроков.

Иногда нет возможности сделать документацию динамической, особенно если вы работаете с корпоративными клиентами. Тогда делайте скриншоты реального интерфейса. Для этого лучше завести демо-стенд с близким к реальности наполнением. И там делать скриншоты.
Можно нарисовать демо-стенд в Figma и из этого собирать медиа для гайда. У меня такой подход не прижился, сложнеё управляться.

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

Очень не люблю стрелочки. Считаю, что лучше выделить место геометрической фигурой и поставить номер шага. Но иногда стрелочки приемлемы, тут вкусовщина.

Из хороших приемов — блюрить лишнюю часть интерфейса или делать выделение лупой важной части.

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

Step-by-step

Step-by-Step — это пошаговое описание всех действий, которые нужно выполнить пользователю, чтобы получить результат.

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

• Делать нумерованные списки. Если есть подпункты, то нумеровать их соответственно и делать сдвиг вправо 1.1, 1.2, 1.2.1 и тд.

• Писать сначала «Что нажать», потом «Где нажать». Исхожу из простой логики — сначала нужно понять «Что искать» и только потом «Где искать».

  Например: «Нажмите на кнопку „Включить“ в правом верхнем углу», а не «В правом верхнем углу нажмите на кнопку „Включить“».

• Вставлять визуальные элементы для кнопок, особенно если они без подписи. Для этой истории приходится немного костылить, если делать это в том же Notion, но в Google Docs это делать проще. Использую стандартные эмодзи и сервис Glyphy.

  Например: Нажмите на символ ⚙️ в правом верхнем углу.

  Не люблю слово иконка, поэтому пишу символ, чтобы была однозначность. Тоже вкусовщина.

• Если одно действие можно сделать из разных мест, описывать все места и каждое по пунктам.

• Если два действия отличаются между собой одним пунктом и кажется бредом писать их два раза, перекреститься и написать два раза. Например, удаление и редактирование часто похожи.

• Все названия кнопок, сущностей, элементов — должны иметь такое же название как в интерфейсе.

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

Поддержка и послесловие

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

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

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

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

1. Когда пишешь большие текстовые документы, глаз замыливается. Можно написать бред и после его не заметить.

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

3. Всегда есть что улучшить. Текст это такой же продукт.

Хочется верить, что эта статья сэкономит кому-то время, а кому-то поможет стать немного лучше.
Я не претендую на истину в последней инстанции. Описал свой опыт и мнение.

p.s. Пользовательская документация с которой все началось. Скажу сразу, там очень много чего можно и нужно улучшить. Бэклог по апдейту документации уже перевалил за 30 задач. Постепенно обновляем.

p.s.s. буду благодарен за конструктивный фидбек в комментариях и ещё больше, если поделитесь вашим опытом.