User manual что это за программа
Руководство пользователя
Руководство пользователя (англ. user guide или user manual), руководство по эксплуатации, руководство оператора — документ, назначение которого — предоставить людям помощь в использовании некоторой системы. Документ входит в состав технической документации на систему и, как правило, подготавливается техническим писателем.
Большинство руководств пользователя помимо текстовых описаний содержит изображения. В случае программного обеспечения, в руководство обычно включаются снимки экрана, при описании аппаратуры — простые и понятные рисунки или фотографии. Используется стиль и язык, доступный предполагаемой аудитории, использование жаргона сокращается до минимума либо подробно объясняется.
Содержание
Содержание
Типичное руководство пользователя содержит:
Все главы и пункты, а также рисунки и таблицы, как правило, нумеруются, с тем, чтобы на них можно было сослаться внутри документа или из другого документа. Нумерация также облегчает ссылки на части руководства, например, при общении пользователя со службой поддержки.
Стандарты
Структура и содержание документа Руководство пользователя автоматизированной системы регламентированы подразделом 3.4 документа РД 50-34.698-90. Структура и содержание документов Руководство оператора, Руководство программиста, Руководство системного программиста регламентированы ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 соответственно.
Зачем нужен мануал
Представить трудно, но в наше время некоторые люди до сих пор не умеют правильно читать. Это надо понимать так: люди не умеют читать инструкции, люди не умеют получить нужную им в данный конкретный момент информацию.
А если человек не умеет «читать» на необходимом уровне, то его ждет беда. Вот почему президент Ассоциации школьных библиотек России Татьяна Жукова считает, что именно это приводит к всевозможным техногенным катастрофам.
Наверное, в наше время найдется еще немало каких-то других причин, которые приводят к чрезвычайным происшествиям. Однако так называемая функциональная неграмотность будет не на последнем месте в печальном списке возможных причин аварий и катастроф. И для того, чтобы ничего подобного не происходило, и существуют так называемые инструкции по эксплуатации.
Что представляет собой этот документ, понять нетрудно. В нем подробно описывается какое-то устройство, а также приводятся правила того, как необходимо пользоваться им. И совсем неважно, что представляет собой это устройство. Это может быть телевизор или компьютер, микроволновая печь или стиральная машина.
Однако все они требует к себе пристального внимания. В том смысле, что во время работы с ними обязательно необходимо соблюдать всё, что написано в инструкции. В противном случае любая машина выходит из строя, а хуже всего, когда это сопровождается травматизмом.
Проявляя заботу о своем клиенте и потребителе, производители всех изделий готовят для них специальные буклеты с подробной инструкцией по эксплуатации. Они обязательно входят в комплект поставки.
Если кто-то называет эту инструкцию по эксплуатации мануалом (manual), то не удивляйтесь. Речь идет об одном и том же. А user guide или user manual в переводе с английского, как нетрудно догадаться, означает руководство по эксплуатации, руководство оператора.
Там есть вся необходимая информация. Что представляет собой изделие? Какие у него части и механизмы? Как необходимо последовательно производить сборку? Как настраивать машину? Как включать и выключать? Ответы на эти и многие другие вопросы, вы найдете в том самом буклете.
Кстати, мануал необходимо воспринимать как солидную работу технического писателя. Это именно он порой очень сложные процессы во всевозможных устройствах описывает так, чтобы перенасыщенный терминами и понятиями язык технических работников был понятен каждой домохозяйке.
А чтобы читать такие тексты было несложно, в буклете обычно в помощь потребителю находится место и для всевозможных иллюстраций, чертежей, схем.
И все для того, чтобы человек все сделал по инструкции, а не как-то иначе. Причем на сегодня существует такое понятие, как пошаговая инструкция. Это означает, что постепенно, шаг за шагом, в определенном порядке, а не иначе следует выполнять требования руководства пользователя. И тогда все получится. Найдется там место и для правил безопасности при работе с оборудованием. Это обязательно! К сожалению, человеку всегда нужно напоминать о том, что электрический ток, работа всевозможных механизмов представляет опасность. Поэтому об этом обязательно пишут в руководствах пользователя тоже.
Причем необходимо подчеркнуть, что пишут все тексты на русском языке, если товар реализуется на территории России. Для любого товара, а уж тем более для какого-либо сложного технического устройства, это очень важно! И совсем не имеет значения, в какой стране произвели ту или иную машину, прибор, аппарат. Инструкция по эксплуатации должна быть только на русском языке.
Производитель обязан собственными силами разрабатывать инструкции по эксплуатации, но он также и заинтересован в этом сам. И потому он ищет неординарные формы подачи материала. То есть он может выполнить инструкцию не только в форме буклета, но в форме наклейки или надписей краской на самом устройстве. Когда мануал находится всегда перед глазами, то его предназначение в таком случае оправдано вдвойне.
Есть и другие формы достучаться до потребителя. Многие компании, особенно всемирно известные, считают необходимым размещать инструкции по эксплуатации в глобальной сети. Отдача от таких Интернет-ресурсов достаточно большая. Ведь при необходимости пользователь может посетить нужный ему сайт, чтобы что-то прочитать, что-то посмотреть и в итоге правильно пользоваться устройством, а тем самым значительно продлить сроки его эксплуатации.
Электронные версии инструкции по эксплуатации, причем в любом формате, сейчас приобретают все большую популярность и находят все большее использование. Пользователь, которому, например, нужен мануал по эксплуатации, может скачать его в pdf, doc, как и в любом другом формате. С учетом того, что у многих дома есть компьютер, электронная версия становится реальностью.
Но иногда бывают такие товары, которые сегодня уже в себе носят пошаговую инструкцию по эксплуатации. Таковым может быть, скажем, телевизор. Достаточно посмотреть на этом самом телевизоре соответствующие видеоролик, чтобы получить ответы на интересующие вопросы по эксплуатации.
Также при покупке можно получить компакт-диск с PDF-файлами. А это предполагает, что у владельца даже полностью автономного ИТ-гаджета обязательно есть дома или на работе компьютер или иное устройство, умеющее выводить PDF-файлы на экран, или печатающее устройство. Действующее законодательство поддерживает такой способ просвещения потребителей.
Остается добавить, что в документации, которая прилагается к товару, вы, конечно, можете найти информацию и о том, как ремонтируют устройство, а самое главное, где находится тот самый сервисный центр, который возьмется за восстановление нормальной работы вашего агрегата.
Что такое User Manual и Service Manual
Приветствую, друзья!
Нас окружает самая разнообразная техника, который мы ежедневно пользуемся — компьютеры, принтеры, телевизоры, пылесосы и много чего еще.
Это всегда сложные агрегаты, и при первом взгляде на них не знаешь – с какого боку подойти.
Большинство используемой нами техники — зарубежного производства. Из зарубежья же пришли к нам в нагрузку эти словосочетания — User Manual и Service Manual.
Без этих мануалов – ни туда и ни сюда!
Что такое User Manual
User Manual (руководство пользователя) — это та самая книжка с картинками, написанная мелким шрифтом, которую лень читать.
Нам надо все сразу и быстро!
И только когда с техникой что-то не ладится — мы начинаем этот самый мануал изучать.
В руководстве пользователя описывается, какой именно техникой нам выпало счастье обладать, ее параметры, энергопотребление, размеры, и тому подобное.
Рассказывается, какими органами управления она обладает, как ей вообще пользоваться.
Современная техника — это умные машины, наделенные электронным интеллектом.
Они способны подавать нам сигналы посредством индикаторов (как звуковых, так и визуальных), сообщающих о ее здоровье.
Чаще всего, зеленые или желтые индикаторы сигнализируют о нормальной работе, красные – о проблемах.
Чем сложнее аппарат, тем толще его User Manual. Так, руководство пользователя на МФУ Xerox 3635 насчитывает 238 страниц!
Начинается сия книга с правил техники безопасности.
Далее там рассказывается подробнейшим образом не только как работать на этом аппарате, но и как выполнить простое техническое обслуживание и устранить некоторые простые неисправности.
Если бы пользователи прочли это руководство, им бы и в голову не пришло совать в такую сложную машину бумагу со скрепками.
Но мало кто читает! Может быть, поэтому уважительное отношение к технике встречается редко.
Зачем нужен User Manual?
Если с аппаратом случилась какая-то проблема, чтение руководства поможет не впасть в ступор и панику. Иногда проблема устраняется простым выключением/включением аппарата. Или нужно вынуть/вставить картридж или вынуть застрявший лист бумаги.
Не нужно вызвать поддержку и платить деньги!
При чтении руководства пользователя можно выяснить интереснейшие вещи. Вот вы, например, знаете, каков уровень излучения вашего мобильного телефона или смартфона? Эти штуки излучают СВЧ энергию, нагревая наш мозг.
Между тем, голова существует в единственном экземпляре, и запчастей к ней не положено!
Много написано о том, как влияют мобильные телефона на здоровье человека. Но всей правды мы, по-видимому, никогда не узнаем.
Но можно выбрать себе аппарат с меньшим излучением, прочитав написанное очень мелким шрифтом.
Что такое Service Manual?
Чем сложнее техника, тем ниже ее надежность. Когда-нибудь она обязательно сломается! Или ее сломает пользователь. И она попадет к сервисному инженеру в ремонт. Вот тут инженеру будет очень кстати Service Manual — руководство по обслуживанию и ремонту.
Это книженция еще толще, чем юзер мануал.
В сервисном руководстве детально расписано и показано на рисунках – как разобрать аппарат. Современная техника содержит микропроцессорную систему или контроллер, которые сигнализируют о ее нездоровье. Сообщение об ошибках могут выводиться на дисплее аппарата.
Это облегчает поиск неисправностей. В хорошем сервисном руководстве для каждой ошибки расписано, что именно следует делать.
Могут приводиться принципиальные схемы блоков устройства, позволяющие понять логику работы и выполнить ремонт с заменой отдельных элементов.
Часто при нарушениях работы сообщения об ошибках не показываются. При этом, чтобы посмотреть код ошибки, надо войти в специальный сервисный режим.
Следует отметить — Service Manual гораздо менее доступен, чем User Manual. Некоторые фирмы-производители считают информацию, размещенную в сервис мануале, конфиденциальной. И предоставляют ее исключительно авторизованным сервисным центрам.
Отметим — в сервисном руководстве описываются процедуры тонкой регулировки и настройки аппарата и его технического обслуживания.
Как мне помог Service Manual
Сервис мануал — очень хорошая штука! Как-то мне попал в ремонт струйный принтер Epson. Он периодически мазал с одной стороны листа. Тщательно осмотрев механическую часть, я никаких поломок не заметил.
Изучив Service Manual, я понял, как регулируется расстояние от печатающей головки до листа бумаги.
Когда я занялся регулировкой, оказалось, что с одной стороны это расстояние невозможно изменить. Точнее говоря, его можно было изменить, но оно не фиксировалось. Долго я таращился то на механику, то на мануал.
Пока не осенило: на заводе изготовителе забыли поставить стойку-опору! В шасси отверстие под нее было, а самой стойки не было. Аппарат прошел технический контроль и какое-то время нормально работал! Дальше уже было дело техники: стойка была изготовлена из подручных материалов и поставлена на штатное место.
Аппарат заработал как швейцарские часы!
Без Service Manual голову пришлось бы напрягать сильнее и дольше…
Заканчивая статью, отметим, что многие (хотя и далеко не все) Service Manual можно найти в интернете. Есть бесплатные библиотеки, есть коммерческие.
Образование – это способ преодолеть превратности судьбы, друзья!
Ускорить смартфон
Все нижеописанные операции с лёгкостью могут превратить ваш смартфон в кирпич! 100 раз подумайте и изучите нюансы, прежде чем что-то делать. И всё забекапить, да.
По умолчанию андроид хрен даст что заблокировать и удалить кроме какого-нить вконтактика. Поэтому я рутанул телефон. Пришлось часов 5 потратить на изучение нюансов и опыта других людей для минимизации косяков. Во время рутования ладошки немного вспотели, но всё обошлось.
Для начала я досконально посмотрел на оперативу, что до рута было мне недоступно: оказалось, что в ней сидит куча хлама, который я использую раз в год и закрываю сразу после использования. Даже если закрыть принудительно процесс в оперативе, то он всё равно скоро сам запустится. Причём это не какой-нить индийский говнософт. Ща уже забылось, но помню яндекс-карты жрали около 50 МБ оперативы. Для масштаба: после загрузки смарта доступны около 500 МБ. И я могу их понять: каждая прога хочет сидеть в оперативе, чтобы быстро запускаться и всякие свои служебные дела делать. Если прога позаботится о пользователе и будет выгружать себя из оперативы, то высок риск что пользователь сменит её на другую, которая быстро запускается, так как сидит в оперативе. А то, что именно из-за неё тормозит смарт пользователь не узнает, ведь таких прог в оперативе множество. Поэтому разработчики вынуждены жертвовать быстродействием смартфона.
На моём смарте около 280 процессов. Думаю, около 100 я на тот момент уже заблокировал. Если посмотреть на названия остальных работающих процессов, то можно увидеть, что присутствует куча ненужного (или редкоиспользуемого) многим хлама. Процессы для bluetooth, VPN, сетевых служб, заставок экрана, фона рабочего стола, шрифтов, принтеров, системных настроек. Заблокировав много чего из перечисленного у меня перестал работать инет и звонки. Пришлось что-то возвращать обратно и блокировать внимательнее. Назначение процессов можно было понять из названий, значков и при помощи гугла.
1. Некоторые приложения при запуске ругаются на отсутствие некоторых гугловских сервисов, но работать ни им, ни мне это не мешает.
3. Не работают приложения Google sheets и Google docs (требуется вагон процессов). Для меня это не большая, но заметная проблема. Поэтому когда приспичит (раз в два месяца), я их использую из браузера.
4. Я заблокировал даже те приложения, которые использую раз в неделю. Соответственно, пару раз в неделю я лезу в Titanium Backup и разблокирую их. На это уходит около 5-10 секунд, но выигрыш от свободной оперативы гораздо больше.
Туториал для туториалов. Как написать пользовательскую документацию
Есть устоявшеёся мнение, что для хороших продуктов руководство пользователя не нужно. Очередной холивар на эту тему разгорелся в нашем рабочем чате. Я не до конца согласен с этим утверждением.
Хороший интерфейс действительно должен помогать пользователю быстро понять продукт и научиться им пользоваться. Как всегда есть пара НО.
Пользователи бывают разные. То есть они могут отличаться как по возрасту, отрасли и опыту, так и по количеству мотивации. Мотивация особенно касается b2b сервисов. Многие пользователи попадают в продукты, потому что «Начальник сказал».
Продукты бывают сложные. Быстро разобраться и понять все их фишки без документации сложно или невозможно.
Документация помогает пользователю решить проблему или помочь разобраться с особенностями и фишками продукта. В любой документации люблю раздел Tips&Tricks.
Что входит в пользовательскую документацию
Пользовательская документация — это не юридические документы. У них другие цели.
Пользовательская документация — это материалы, которые помогают пользователю использовать продукт на максималках.
Что еще можно отнести к пользовательской документации
Документация для разработчиков и администрированию: доки по API, инструкции по установке и администрированию. Но сейчас их касаться не буду.
В пользовательскую документацию я включаю:
Ответы на часто задаваемые вопросы (FAQ).
Руководство пользователя. Это самый жирный кусок из всей пользовательской документации. Здесь описывается весь интерфейс, только текстом.
Краткое руководство пользователя. Короткая презентация или документ для быстрого начала. Описывает базовые функции, возможности и советы для начала. Главное отличие от полного руководства — быстрее читаются, дают базовое представление о продукте и особенно помогают при внедрении b2b продуктов.
Описание отдельных фишек (Tips&Tricks). Чаще всего их делают в формате видеоуроков, но можно наткнуться и на текстовые.
Релизноуты. Считаю их важной частью пользовательской документации. И, говоря релизноуты, я имею ввиду не разовые, которые выкладываются в магазины приложений или к себе на сайт. А написанные раз в какой-то период. Можно раз в месяц. При работе над прошлым продуктом мы писали всё, что исправили или добавили за месяц. Хорошим тоном, на мой взгляд, будет писать самое важное.
Видеоуроки. Считаю их частью пользовательской документации, но это скорее вкусовщина, чем правило.
Почему это важно?
Хорошо написанная пользовательская документация помогает разгрузить поддержку. Особенно если первый контакт у вас происходит через бота. Боты берут ответы на типовые вопросы из документации. А если большая часть ваших запросов типовые, несложно подсчитать насколько это разгружает поддержку.
Если в вашей поддержке сидят операторы, то документация поможет им найти ответ на вопрос, если они не знают и быстро скопировать нужный текст для отправки. Или вообще отправить ссылку на кусок документации, который решает проблему пользователя.
Документация помогает пользователям разобраться в продукте или узнать какие-то неявные фишки. Я, например, часто ползаю в гайды разных продуктов, чтобы посмотреть как какую-то штуку сделать и можно ли её вообще сделать.
Документация помогает вам работать с корпоративными заказчиками, но об этом дальше.
Красоты B2B рынка
Прошлый продукт, над которым мы с командой работали, умел и в облако, и в on-premise.
С облаком все понятно. Динамическая документация на сайте или в другом сервисе. Документация для корпоративных заказчиков имеет определенные особенности.
Особенность #1: Корпорации любят печатную документацию. Очень сильно.
Мой знакомый сейлз любит рассказывать истории про это.
Резюме его историй:
Если вдруг что, отчитываться о покупке, установке и эксплуатации корпорации будут большими стопками документации.
Поэтому чем толще кипа бумаги — тем лучше.
Особенность #2: Нужно отдавать дополнительные пакеты документов.
В дополнительные пакеты документов входит: документация по установке вашего ПО и документацию по его администрированию, а может ещё что-то, если попросят.
Особенность #3: Документацию, которую вы отдаете корпоративному заказчику, нужно будет поддерживать отдельно.
Реальность работы с большими корпоративными заказчиками в том, что ваш продукт требует доработки для решения их задач. Всегда есть какие-то нюансы и дополнения. Поэтому отдавать им облачную документацию, чаще всего, не получится.
Особенность #4: Встречается реже, но тоже требует внимания. Если ваш продукт визуально кастомизируется (меняются цвета, меняется расположение кнопок), то для каждого заказчика с нестандартным интерфейсом нужно будет делать свою документацию. Это не правило, а скорее хороший тон и забота.
Где делать?
Много думал, долго смотрел. Переделывал наш гайд раз пять.
Когда искал, ставил для себя следующие задачи:
Документацию можно сделать динамической. То есть возможность грузить видео, гифки, делать кросс-ссылки.
Поддерживается базовое форматирование: заголовки, жирный, курсив, code, code block.
Есть возможность выложить документацию на свой домен.
Есть возможность кастомизации для заказчиков. Поменять цвета, добавить логотипы и прочее.
Какие вариант рассматривал:
Самописные.
Стоимость: может быть любой и измеряться в человеко-часах.
Плюсы: можно накрутить и наворотить, что по кайфу.
Минусы: долго, дорого, больно, потому что полноценный отдельный продукт, но для компаний больше 100 человек, может быть хорошим решением.
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.
Ещё есть классный сервис Типограф, он поможет поставить нормальные кавычки, убрать лишние пробелы, в нужных местах заменить дефисы на тире и поправить другую экранную типографику.
Если ваш продукт международный
Правила выше применяются к русскому языку. Если ваш продукт международный, то нужно оформлять по международным правила. В некоторых местах правила могут сильно отличаться от наших стандартов.
Удобная навигация
Нет единого мнения — как правильно. Если самопис, я рекомендую делать вертикальную навигацию слева. Такая часто встречается в технических документациях.
По структуре, на мой взгляд, можно выделить такие блоки:
Блок общего и важного.
Описание вашего решения. Вдруг пользователь попал сначала на ваш гайд, а не на сайт.
Какие есть приложения, со ссылками на скачивания или как пользоваться, если это например веб-версия.
Блок «Как начать». Сюда писать общие вещи, которые касаются всего сервиса. Особенно важный блок, если у вас мультиплатформенное решение.
Блок с руководством пользователя. Если у вас мультиплатформенное решение, то на каждую платформу лучше писать свое руководство. Можно объединять мобильные приложения и ПК версию. Так можно делать если нет глобальной разницы.
У нас, например, исторически разницы не было. Поэтому iOS и Android лежат на странице «Мобильные приложения». Но сейчас мы начали разделять, поэтому в будущем будет разделение на ОС.
Связность
Продукт — это всегда комплекс фич. И они часто между собой связаны. Если в одном месте упоминается другая фича, давайте ссылку на страницу или пункт.
Если хочется сделать по красоте, то можно внимательно изучить методологию Zettelkasten, например.
Удобный поиск
Тут много писать не буду. Если пользователь попал в документацию с конкретным запросом, у него должна быть возможность быстро найти то, что ему надо. Пользователь — не Индиана Джонс и охотиться за минотавром в вашей навигации не планирует.
Вот как мы это в Notion решили.
Логичность
Всё, что вы пишите должно быть логичным.
Порядок элементов в тексте и интерфейсе должен быть одинаковым. Пользователь ломается, когда написано: «Нажмите на вторую вкладку „Контакты“», а вторая вкладка — «Чаты».
Или когда в интерфейсе элемент называется «Назначить админом», а написано «Назначить администратором».
Понятная визуалка
Этот пункт я бы хотел разбить на два блока: работа с медиа и работа с Step-by-Step.
Работа с медиа
Иногда нет возможности сделать документацию динамической, особенно если вы работаете с корпоративными клиентами. Тогда делайте скриншоты реального интерфейса. Для этого лучше завести демо-стенд с близким к реальности наполнением. И там делать скриншоты.
Можно нарисовать демо-стенд в 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. Всегда есть что улучшить. Текст это такой же продукт.
Хочется верить, что эта статья сэкономит кому-то время, а кому-то поможет стать немного лучше.
Я не претендую на истину в последней инстанции. Описал свой опыт и мнение.