Инструкция по пользованию приложением

Содержание статьи:

• Что такое руководство пользователя и почему оно необходимо
• Общие рекомендации по разработке руководств пользователя
• Виды руководств пользователя
• Структура руководства пользователя программы
• Преимущества создания РП на онлайн-платформе управления документацией

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

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

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

Что такое руководство пользователя и почему оно необходимо?

Руководство пользователя (РП) – это документ, который предоставляет подробную информацию о том, как использовать определенное оборудование, программу или сайт. В руководстве предоставляются инструкции по установке, порядок выполнения последовательности действий по настройке и использованию оборудования или ИТ-продукта, а также описание функций, возможностей и рекомендации по их использованию.

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

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

При разработке РП следует учитывать несколько факторов:

• Целевая аудитория. Определите, кому предназначено ваше РП. Учитывайте уровень их знаний и опыта в использовании программы или сайта. Например, если руководство предназначено для начинающих (рядовых пользователей), необходимо предоставить более детальные пошаговые инструкции. Если аудитория – это люди, которым нужны особые, нечасто используемые функции программы/сервиса, то РП должно иметь другую глубину изложения материала.
• Язык. Язык должен быть ясным и доступным. Необходимо избегать технических терминов и особенно профессионального сленга – жаргона, на котором говорят специалисты. Как правило, он непонятен рядовым пользователям, поэтому не заставляйте их читать РП со словарем. Объясняйте термины, которые могут быть незнакомы новым пользователям.
• Стиль. Определенные типы документов позволяют использовать яркий, почти «рекламный» стиль изложения. Однако, стилистически окрашенная лексика может отвлекать пользователя от содержания. Поэтому оптимальным вариантом будет написать РП в нейтрально-официальном формате.
• Структура. Разделите руководство на логические разделы и подразделы, чтобы облегчить поиск информации. Обязательно пронумеруйте страницы. Это позволит облегчить навигацию по документу. Этой же цели служат и гиперссылки.
• Практические примеры. Иллюстрируйте РП практическими примерами использования программы или сайта. Это поможет пользователям лучше понять, как применять их на практике.
• Иллюстрации. Добавьте скриншоты, диаграммы и другие визуальные материалы и инфографику. Это сделает документ более сбалансированным (уравновесит соотношение «текст – визуальные материалы») и даст пользователям отдохнуть от обилия текста.
• Обратная связь. Предоставьте контактную информацию, чтобы пользователи могли задавать вопросы или давать обратную связь о руководстве.
• Обновление. Руководство пользователя должно регулярно обновляться в соответствии с изменениями в программе или на сайте.

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

Виды руководств пользователя

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

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

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

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

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

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

Руководство пользователя сайта имеет место, когда речь идет о программном обеспечении как услуге (англ. software as a service или SaaS). По сути, данное РП представляет собой способ коммуникации между провайдером услуги и пользователем. В документе описывается принцип отношений двух сторон: подписчики получают доступ к готовому ПО в облаке через мобильное приложение или веб-браузер, которое обслуживается провайдером (он занимается установкой, обновлением и обслуживанием).

Руководство пользователя сайта и руководство пользователя программы фактически имеют минимальные отличия. Основной упор делается на то, как пользоваться новым инструментом, однако в случае руководства пользователя сайта данный инструмент (программа) размещается на сайте владельца.

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

Каждое РП имеет свои особенности, которые определяют его структуру. Поэтому сложно выработать общие рекомендации и требования, которые будут применимы ко всем случаям. Если вы все-таки ищете универсальные рекомендации, то вам следует обратиться к РД 50-34.698 (Комплекс стандартов и руководящих документов на автоматизированные системы), где перечислены самые частотные разделы, встречающиеся в руководствах пользователя (соответствует ГОСТ):

• Введение. Содержит краткое описание области применения ПО и его функционал;
• Назначение. В данном разделе дается ответ на вопрос «зачем?» (зачем пользователю данное приложение, для чего оно служит, какие задачи призвано решить, как облегчает жизнь пользователя и т.д.);
• Подготовка к работе. В данном разделе приведена информация о том, что необходимо для начала работы. Описывается комплектность дистрибутива, процедуры установки и загрузки, а также способы функциональных испытаний;
• Описание операций. Это основной и самый объемный раздел, в котором с помощью подробных инструкций и скриншотов описываются функции программы. Таким образом пользователь понимает, как работать с данными и выполнять конкретные задачи.
• Аварийные ситуации. Содержит описание аварийных ситуаций (неисправностей и сбоев в работе программы) и инструкции по их ликвидации;
• Рекомендации. В этом разделе предлагаются примеры использования ПО или сервиса, которые позволяют пользователям совершенствовать свои навыки владения данным инструментом.

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

Преимущества создания РП на онлайн-платформе управления документацией

Современные средства для создания и управления документацией преимущественно существуют в форме ПО, предоставляемом в качестве услуги (software as a service). Они представляют собой максимально удобные инструменты для оформления РП.

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

При интеграции в корпоративную информационную систему Документерра дает пользователям следующие преимущества:

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

***

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

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

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

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

Определи аудиторию

Картинка с сайта: brodude.ru

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

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

Придерживайся последовательности действий

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

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

Сделай материал полезным для читателя

Картинка с сайта: brodude.ru

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

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

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

Подбери иллюстрации

Картинка с сайта: brodude.ru

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

В этот же пункт отнесём и видеоинструкции. Короткий и понятный видеоролик по работе приложения иногда может удачно использоваться в ситуации, когда требуется слишком много изображений. Если нужно самостоятельно записать качественный видеоролик, можно воспользоваться специальными программами, например, REC — Screen Recorder. Это бесплатный софт для записи экрана в высоком качестве в форматах UHD, FHD, HD, HQ, SD.

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

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

Расскажи о личном опыте

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

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

Проведи тест-драйв

Картинка с сайта: brodude.ru

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

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

Конкретных правил составления гайдов любой направленности нет, но мы надеемся, что статья поможет приступить к написанию инструкции для твоего приложения и добиться желаемого результата. Воспользовавшись программами для записи видеопроигрывателей, трансляций и руководств, ты существенно упростишь себе жизнь. Возможно, в этом тебе пригодится REC — Screen Recorder, которым пользуются более 73 тысяч пользователей. 

Общая информация

Мобильное приложение «Особый взгляд» (далее — приложение) предназначено для автоматической синхронизации и воспроизведения тифлокомментариев к художественным, анимационным, документальным фильмам и другому видеоконтенту, и для тифлокомментирования в реальном времени театральных постановок, цирковых представлений, спортивных состязаний, экскурсий и прочих массовых зрелищных и культурных мероприятий. Для автоматизированной синхронизации и тифлокомментирования кино и другого видеоконтента приложение сканирует звук источника через встроенный микрофон устройства и воспроизводит через встроенный динамик или подключённый наушник в соответствии с текущим моментом кинофильма, видеоролика или телепрограммы. Для тифлокомментирования в реальном времени приложение служит в качестве передатчика голоса тифлокомментатора и приёмника для незрячего зрителя, используя текущее интернет-соединение по беспроводной сети или сотовой связи.
Важно! Приложение не содержит и не транслирует фрагментов аудио- или видеоматериалов видеоконтента и тифлокомментируемых мероприятий. Только звуковую дорожку тифлокомментария или голос тифлокомментатора.
Для корректной работы приложения устройство пользователя должно находиться в зоне слышимости звука фильма и другого видеоконтента, транслируемого без искажений или в месте непосредственного проведения мероприятия, а мембрана микрофона устройства не должна быть перекрыта.
Приложение работает на устройствах с операционной системой Android версии 6.0 и выше.

Установка

Установить мобильное приложение «Особый взгляд» можно в магазинах приложений «Google play”, пройдя по ссылке Скачать приложение Google Play или «Rustore», пройдя по ссылке Скачать приложение Rustore
А также загрузить установочный файл, пройдя по ссылке: Скачать приложение
Обратите внимание: если вы используете установочный файл, то нужно разрешить установку из сторонних источников в настройках устройства.

Стартовое меню

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

Первый запуск

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

Запрос на использование микрофона

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

Запрос на совершение звонков

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

Разрешение на получение уведомлений

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

Краткая инструкция по использованию приложения

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

Кино

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

Новинки

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

Подборки

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

Популярное

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

Вкладки

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

Каталог

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

Сортировка

Для эффективного поиска нужных позиций в каталоге в нем содержатся три инструмента, которые можно использовать как вместе, так и по отдельности.
Сортировка позволяет располагать позиции каталога или результаты поисковой выдачи в удобном для пользователя порядке.
Кнопка «Сортировка» располагается в верхнем правом углу экрана раздела «Каталог». Ее активация раскрывает список возможных результатов сортировки: по дате публикации, по году премьеры и по названию. А также те же варианты сортировки в обратном порядке, они помечены словом «Убывающий».
Для активации выбранного способа сортировки нужно активировать соответствующий пункт. Меню выбора закроется, каталог отобразится в нужном виде. Для того чтобы покинуть меню выбора вариантов сортировки, нужно нажать кнопку «Отмена» в конце списка.

Фильтр

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

Поиск

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

Карточка тифлокомментария

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

Синхронизация тифлокомментариев

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

Загрузка и удаление тифлокомментариев

Для того чтобы загрузить тифлокомментарий на устройство, нужно нажать в открытой карточке фильма кнопку «Загрузить тифлокомментарий», расположенную внизу экрана. Во время загрузки кнопка «Загрузить тифлокомментарий» изменится на уведомление «Тифлокомментарий загружается», а после окончания процесса на этом месте появится кнопка «Начать синхронизацию».
Тифлокомментарии загружаются только во внутреннюю память устройства. Средний размер одного тифлокомментария — 30 МБ.

Удаление и оценка

После загрузки тифлокомментария в открытой карточке фильма в верхнем правом углу появятся кнопки «Оценить тифлокомментарий» и «Удалить из тифлотеки».
При нажатии кнопки «Оценить тифлокомментарий» откроется диалог оценки. Он представляет собой интерактивный элемент, активировав который можно выбрать оценку от одного до пяти. Там же будет поле для ввода текста, в нем можно написать отзыв о тифлокомментарии.
Написание отзыва не является обязательным для завершения процесса.
После выставления оценки, нужно нажать кнопку «Отправить», расположенную слева под полем ввода отзыва. Чтобы покинуть диалог, нужно нажать кнопку «Отмена», расположенную справа под полем ввода отзыва.
Для того чтобы удалить тифлокомментарий, нужно нажать кнопку «Удалить из тифлотеки», расположенную в правом верхнем углу экрана открытой карточки фильма.
Важно! тифлокомментарий удаляется из тифлотеки без диалога подтверждения.

Тифлотека

Все загруженные тифлокомментарии отображаются в разделе «Тифлотека».
Раздел организован в виде списка, позиции которого расположены по убыванию времени загрузки, где первая позиция — последний загруженный тифлокомментарий.
Если загруженных тифлокомментариев нет, то в разделе отображается текст: «В вашей тифлотеке пока пусто. Загружайте фильмы из каталога, и они появятся здесь».

Синхронизация и воспроизведение

Для того чтобы запустить процесс синхронизации и воспроизведения тифлокомментария, необходимо нажать на кнопку «Начать синхронизацию».
При активном процессе синхронизации кнопка «Начать синхронизацию» изменится на кнопку «Остановить синхронизацию», а также появится счетчик, указывающий текущее время фильма.
Выше кнопки остановить синхронизацию» появится кнопка «перезагрузка». Её активация сбросит синхронизацию и воспроизведение и запустит процесс заново. Эта опция необходима для перезагрузки процесса в случае некорректной синхронизации тифлокомментария.
Важно! Воспроизведение тифлокомментария не начнется до тех пор, пока приложение не отсканирует звук фильма из внешнего источника – акустической системы кинотеатра, телевизора и пр.
Чтобы остановить синхронизацию и воспроизведение тифлокомментария, нужно нажать на кнопку «Остановить синхронизацию». После остановки она снова изменится на «Начать синхронизацию», а счетчик и кнопка «Перезагрузка» исчезнут.
При потере сигнала из внешнего источника, а также в случае остановки или приостановки фильма, синхронизация и воспроизведение не остановятся.
Приложение само поймет, когда он начнется, отсканирует звук и запустит воспроизведение тифлокомментария.

Фоновый режим и наушники

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

Настройки

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

Выбор темы оформления

Этот параметр выполнен в виде раскрывающегося меню и содержит три позиции: автоматически (выбрано по умолчанию, зависит от настроек устройства), темная тема и светлая тема. Для того чтобы установить выбранную тему, нужно активировать соответствующий пункт. Чтобы свернуть меню, активировать установленный пункт.

Выбор размера шрифта

Определяет размер шрифта интерфейса приложения. Содержит четыре параметра: маленький, средний (выбран по умолчанию), большой и огромный. Чтобы установить выбранный шрифт, нужно активировать соответствующий пункт. Чтобы свернуть меню, активировать установленный пункт.

Отображать 18+

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

Только наушники

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

Выбор канала наушника

Этот параметр оформлен в виде раскрывающегося меню, он регулирует канал воспроизведения тифлокомментария через наушники. Содержит три пункта: оба (выбран по умолчанию), правый и левый. Чтобы установить выбранный канал, нужно активировать соответствующий пункт. Чтобы свернуть меню, активировать выбранный пункт.

Запрет скачка назад

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

Запрет скачка вперёд

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

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

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

Обратная связь с разработчиками

Нажатие этой кнопки переводит к форме обратной связи на сайте проекта. Форма откроется в новой вкладке браузера, установленного на устройстве по умолчанию.

Оставить отзыв

Активация этого пункта откроет форму оценки приложения в магазине приложений «Google play».

Тифлокомментирование в реальном времени

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

Вкладки

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

Главный экран

Интерфейс каждого раздела представляет собой список мероприятий, расположенных в хронологическом порядке, начиная с ближайшего по времени проведения.
В списке каталога указаны название мероприятия, место и время проведения.
Для того, чтобы подключиться к трансляции необходимо выбрать нужную позицию каталога и активировать её. Раскроется карточка мероприятия.
Для того, чтобы вернуться на главный экран приложения, нужно нажать кнопку «На один уровень вверх» в левом верхнем углу или использовать стандартный жест перехода на один уровень назад.
В правом верхнем углу главного экрана разделов «Спорт», «Театр» и «Цирк», находится кнопка «Фильтр», которая активирует настройки фильтрации отображения каталога мероприятий.

Поиск и фильтрация

В правом верхнем углу главного экрана разделов «Спорт», «Театр» и «Цирк», расположена кнопка «Фильтр», Активация которой открывает меню фильтрации позиций каталога мероприятий. Меню содержит несколько пунктов, представляющих собой раскрывающиеся списки. Для настройки параметра фильтрации нужно активировать пункт меню и установить значение параметра. После выбора всех необходимых параметров, нужно нажать кнопку «Применить фильтр» в нижней части экрана. Меню фильтра закроется и каталог мероприятий отобразится в установленном виде – отобразятся только мероприятия, соответствующие выбранным параметрам.
Чтобы отменить выбор параметров, нужно нажать кнопку «Сбросить фильтр» в правом верхнем углу экрана.
Чтобы вернуться на главный экран раздела, нужно нажать кнопку в левом верхнем углу экрана или использовать стандартный жест перехода на один уровень назад.

Карточка мероприятия

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

Подключение к трансляции

Чтобы подключиться к трансляции мероприятия, нужно в его карточке активировать кнопку «Подключиться к трансляции». После удачного соединения кнопка «Подключиться к трансляции изменится на кнопку «Отключиться от трансляции», а рядом появится кнопка «Перезапустить», нажатие которой сбросит и заново произведёт подключение. В случае неудачного подключения появится сообщение об ошибке.
Важно! Соединение произойдёт только в том случае, если трансляция началась. Если тифлокомментатор не запустил трансляцию появится сообщение «Трансляция ещё не началась».

Защищённые трансляции

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

Избранное

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

Фоновый режим и наушники

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

Настройки

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

Выбор темы оформления

Этот параметр выполнен в виде раскрывающегося меню и содержит три позиции: автоматически (выбрано по умолчанию, зависит от настроек устройства), темная тема и светлая тема. Для того чтобы установить выбранную тему, нужно активировать соответствующий пункт. Чтобы свернуть меню, активировать установленный пункт.

Выбор размера шрифта

Определяет размер шрифта интерфейса приложения. Содержит четыре параметра: маленький, средний (выбран по умолчанию), большой и огромный. Чтобы установить выбранный шрифт, нужно активировать соответствующий пункт. Чтобы свернуть меню, активировать установленный пункт.

Отображать 18+

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

Только наушники

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

Время по месту события

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

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

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

Обратная связь с разработчиками

Нажатие этой кнопки переводит к форме обратной связи на сайте проекта. Форма откроется в новой вкладке браузера, установленного на устройстве по умолчанию.

Оставить отзыв

При активации этого пункта откроется профиль приложения в «Google play», в котором, в том числе, можно поставить ему оценку и написать отзыв.

Заключение

Благодарим вас за использование мобильного приложения «Особый взгляд»!

По всем вопросам, связанным с работой приложения, обращайтесь, пожалуйста, на электронную почту: tiflokomment@specialview.org или воспользуйтесь формой обратной связи на сайте проекта.
.

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

Сказ о том, как для андроидного приложения бумажное руководство писали

Я пять лет разрабатываю техническую документацию. Всё это время руководящими документами были и ГОСТы групп 2, 7, 19 и 34, и разная экзотика вроде приказа Минпромторга № 4091 от 15.12.2015. Руководящие документы облегчают жизнь, сводя необходимость думать к размышлению о содержимом документа, а уж структуру и оформление диктует стандарт. Однако есть и сложности. Следуя стандартам, получишь стандартный документ, однако стандартный не значит удобный для чтения и исчерпывающе полный. Средства разработки документации — обычно это текстовые процессоры из офисных пакетов — требуют большой подготовительной работы по наруливанию стилей и организации рамок, чтобы привести результат работы к стандартному виду. Если же подготовкой пренебречь, через полсотни страниц документ станет технически неуправляемым. Наконец, прохладное отношение разработчиков к документации приводит к тому, что её разрабатывают или по остаточному принципу, или так, чтобы принял заказчик. Заказчик же в первую очередь ориентируется на критерии нормоконтроля, отнюдь не задумываясь о мере, в какой документ пригоден для чтения и понимания людьми.

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

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

Понять задачу

Задача была поставлена предельно просто: написать руководство пользователя для андроидного приложения HF Pager. Вскоре после начала переговоров решено было сделать бумажное руководство.

Руководство пользователя для андроидного приложения само по себе невероятная редкость — я сходу не смог вспомнить ни одного примера, тем более на бумаге. Затея сделать печатное руководство пользователя приложения на смартфоне нетривиальна, однако здравое зерно в этом есть. Бумажная документация не требует энергии и интернета, может быть продана как материальный предмет или предъявлена окологосударственным пользователям. Наконец, при должном подходе к печати бумажная документация солидно выглядит. Как бы ни была изготовлена документация, главная её задача — уменьшить нагрузку на хелпдеск. С этим соображением я и подошёл к делу.

Годное руководство пользователя — это ясная структура и необходимая достаточная полнота изложения.

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

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

Референс — отвечает на вопрос «Что это такое?». Подход схожий: выписать сущности, каждую пояснить, и ни слова сверх того. Порядок изложения сущностей — хронологический, от общего к частному, от очевидного к неочевидному, сверху вниз слева направо. В этой работе самое сложное — каждый раз вовремя остановиться. В моём случае референс состоит из двух уровней. На уровне оперативной справки для быстрого знакомства — картинки с основным экраном приложения с минимумом пояснений. Уровень детальной справки посвящён меню. Референс по меню написан преимущественно текстом, структура описания пунктов меню везде одинаковая: что это такое → что делает → значение по умолчанию. В отдельных местах я счёл целесообразным добавить ремарки в виде единообразно оформленных замечаний («Не трогай тут ничего») или советов («Прикрути фитиль, если по умолчанию слишком ярко»). Оформление придумал сам и вынес в раздел типографских соглашений, где ему и место.

Картинка с сайта: habr.com

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

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

Когда был готов проект большого руководства, внезапно оказалось, что нужно ещё одно, маленькое — quick start guide, руководство по быстрому старту, или просто РБС. Дело в том, что приложение предназначено для эксплуатации в полевых условиях без интернета, поэтому нужна шпаргалка по приложению, чтобы носить при себе. Требования к РБС те же, что и к руководству пользователя — ясная структура и полнота изложения. Из условий эксплуатации РБС следует ещё эргономические требования. На эргономике позже остановимся подробнее.

Структура РБС затруднений не вызвала: в РБС входит лишь то, что пригодится в полевых условиях. Поскольку задачи условно делятся на рабочие и служебные, оставить нужно только рабочие. Референс — на минималках, концепт не нужен. В итоге из руководства пользователя в РБС остались только три задачи, императивная справка по настройке, краткая справка по устранению неисправностей, и два чеклиста: один перед выходом на маршрут, другой — перед сеансом связи. Переиспользование контента наше всё, поэтому решения задач переехали в РБС без изменений, а вот справки и чеклисты я написал «с нуля».

Технология

Выбор средства производства «документа, содержащего в основном сплошной текст», не самоочевиден. Исходные предпосылки выбора таковы:

• документ предназначен для печати, но потом может потребоваться электронная версия;

• подход doc as a code по сравнению с традиционным более громоздкий, но облегчает переиспользование контента;

• работать придётся с текстом и картинками, притом много и гибко;

• на сказанное в ГОСТ 19 ориентироваться не надо;

• Микрософт Ворд для серьёзной и тонкой работы с текстом неудобен, его аналоги тоже.

Поэтому на роль средств производства я выбрал VS Code для текста, Adobe Illustrator для картинок, и Adobe InDesign для создания непосредственно документа. Применять именно этот софт не обязательно: другие текстовый блокнот, векторный редактор и DTP-система способны решить ту же самую задачу. Текстовый блокнот, в отличие от текстового процессора, легко интегрируется с системой контроля версий — со вытекающими из этого удобствами работы с текстом. Необходимость векторного редактора для технической иллюстрации в пояснениях не нуждается. Для оформления текста в документ DTP-система лучше условного Ворда настолько же, насколько для резьбы по дереву стамеска и нож лучше чем топор-колун.

Отдельно поясню про формат текста: я выбрал обыкновенный неформатированный текст, а не маркдаун или ReST. Выбор формата в таком деле всегда компромисс: простой текст проще писать и читать, но сложнее конвертировать и переиспользовать автоматически, обратное тоже справедливо. В моём случае ключевым фактором стало взаимодействие с Индизайном: простой текст просто вставляется в текстовый фрейм прямо из буфера обмена. Это не лучший способ: можно было прилинковать текст к фрейму, и тогда бы макет автоматически обновлялся при правках текста. На больших документах лучше так и поступать, на небольших — можно обойтись и копипастой.

Индизайн прекрасен, но есть нюанс

Обратная сторона гибкости DTP — сравнительно трудоёмкое обновление документа в тот момент, когда от заказчика работ приедут серьёзные правки в текст. В этот раз правки приехали уже на этапе окончания вёрстки, и немедленно оказалось, что добавить короткий раздел в самое начало свёрстанной страницы нельзя, если не перебрать вручную вообще всё до следующего раздела. Конечно, есть прекрасные средства автоматизированной подготовки документации, умеющие в CI без участия оператора ЭВМ, но прежде уже было решено не оглядываться на ГОСТ 19, поэтому закат солнца каждый раз пришлось делать вручную.

Картинка с сайта: habr.com

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

Инструкция по оригами

Выше я отметил, что РБС физически представляет собой лист бумаги, защищённый ламинацией или пластиковым пакетом, и свёрнутый дважды пополам так, чтобы получалось 4 маленьких страницы для информации первоочередной важности, и на обороте ещё столько же для относительно второстепенных сведений. Изобразить это в Индизайне не составило труда: фреймы с текстом легко поворачиваются на нужный угол. Чтобы разобраться с ориентацией фреймов на листе, согнул из листа бумаги макет.

Картинка с сайта: habr.com

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

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

Пришлось искать другое решение. Для этого сформулировал критерии хорошей инструкции по оригами:

• настолько однозначная, насколько возможно;

• визуально заметная, но не бросается в глаза при дальнейшем использовании документа;

• предельно короткая;

• скорее длинная, чем широкая (высокая), поскольку на линию сгиба заложено всего 10 миллиметров;

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

Картинка с сайта: habr.com

Картинка с сайта: habr.com

Картинка с сайта: habr.com

Окончательное решение придумал с четвёртой попытки, остановившись на серых надписях жирным серым моноширинным шрифтом: «линия первого сгиба этой стороной внутрь», «линия второго сгиба — на противоположной стороне листа», «линия второго сгиба этой стороной внутрь». Существительные выглядят менее навязчиво, чем глаголы; моноширинный шрифт подчёркивает специальное предназначение надписи и несколько купирует эффект близости, благодаря которому объекты, расположенные ближе друг к другу, выглядят сильнее взаимосвязанными.

Вероятно, идеальное решение — организационное: централизованно отпечатать и согнуть как надо.

Нам всем мешает знание

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

Описать сбалансированно таск или референс относительно несложно: таск — о том, что пользователь делает; референс — о том, что пользователь видит и нажимает. В обоих случаях абсолютно необходимый объём изложения и есть достаточный. Иначе дело обстоит с концептами: они посвящены тому, что пользователь не знает.

Это ключевой момент: когда для автора всё понятно, как автору понять, что не знает пользователь? По логике™ — спросить об этом у самого пользователя, а ещё вернее, сделать так, чтобы пользователь сам об этом рассказал. Сам пользователь рассказывает исключительно хелпдеску или тому, кто за него — например, знание о незнании я почерпнул в чате сообщества пользователей приложения.

Так в разделе концептов появились четыре темы: объёмная «Организация радиосвязи», сложная и абстрактная «Однополосная модуляция», лёгкая «Выбор скорости манипуляции», и просто справочная «Использование маяка». Написать о том, как я решил задачу изложения этих тем, мне тоже мешает знание: я их просто взял и изложил. На это, однако, было израсходовано 2 дня времени и 6,5 тысяч знаков текста в тысяче слов, основной труд состоял в постоянном отвечании на заданный самому себе вопрос «Что реально надо знать пользователю об этом?»

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

Для незнакомых с радиотехникой поясню: это как если рассказ о Налоговом кодексе РФ свести к пояснению, как считать сумму к начислению заработной платы по величине выплаты «на руки».

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

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

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

Важные мелочи

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

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

То есть, в принципе, всё то же самое, что ГОСТы 19.106 и 19.505, но с человеческим лицом.

Картинка с сайта: habr.com

Одной структурой в техническом документе не обойтись, нужна ещё навигация. Для навигации по документу использованы колонтитулы и оглавление с нумерацией страниц, а для навигации по странице — типографика. Колонтитулы не повторяют заголовки, и названы обобщённо по тому, какого рода материалы под собой они объединяют. Перекрёстные ссылки, в том числе на рисунки, также ссылаются просто на номера страниц. Это стало возможным благодаря тому, что каждый рисунок, на который в документе есть ссылка, на странице ровно один. Остальные рисунки расположены по принципу близости к абзацам, в которых они упоминаются, поэтому удалось приемлемо обойтись без подрисуночных подписей с нумерацией рисунков. Абсолютное большинство рисунков без подписи собрано в разделе справки по интерфейсу, и ссылаться на такие рисунки не нужно.

Картинка с сайта: habr.com

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

Картинка с сайта: habr.com

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

Тестирование документации и обратная связь

Документация — такой же продукт, как и то, что она документирует, поэтому тоже подлежит тестированию. В моём случае тестирование прошло прямо на пользователях: РБС и руководство пользователя заказчик зарелизил прямо в чате поддержки приложения, и через полчаса туда посыпались отзывы. Большинство — с благодарностями, но нашлись также энтузиасты, высказавшие по существу. Один из них вовсе написал целый протокол разногласий объёмом 5 страниц. Несмотря на то, что критика почти не повлияла на содержимое документов, руководство пользователя обновилось три раза. В документах нашлись помарки: например, я неправильно настроил форматирование перекрёстных ссылок, из-за чего образовались лишние слова, и вёрстка расползлась. Ещё пришлось изменить отдельные формулировки: в одних уточнили смысл, в других улучшили читаемость.

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

• Почему бы не написать, какие разрешения дать приложению?

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

• А почему не сказано, что надо включить режим VOX на радиостанции?

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

• Почему нет раздела о настройке однополосной модуляции?

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

• А перенесите раздел «Ограничения демо-версии» в раздел «Регистрация приложения»?

• Нет, потому что регистрация — обязательная операция для всех, а вот ограничения демо-версии — информация справочная, и нужна она только тем, у кого демо-версия есть, а это вообще отдельное приложение.

• Добавьте, что в однополосной модуляции принято работать верхней боковой полосой в цифровых режимах?

• Нет, потому что у нас не руководство по радиосвязи.

Может показаться, что пользователей послали. На самом деле это не так. Область определения документа, структура и достаточная полнота содержания — это то, что ограничивает документ в интересах пользователя. Если его запросы выходят за пределы области определения, значит, нужно просто написать ещё один документ.

Замечания к тексту разделились на два класса: замечания к структуре и содержанию, и замечания к формулировкам. Различаются эти классы тем, что замечания к формулировкам изменяют смысл сказанного, а замечания к структуре и содержанию — смысл дополняют, но не изменяют. Замечания к структуре и содержанию объясняет желание пользователей увидеть всеобъемлющее руководство по радиосвязи с помощью приложения. Такие замечания интересны для понимания того, как пользователи мыслят и читают, но переносить их в документацию надо с осторожностью, иначе в попытке объять необъятное легко получить неподдерживаемую спагетти-структуру. А вот замечания к формулировкам ценны: если пользователь формулировку не понял, или понял неправильно — это проблема документации, которую нужно выявить и исправить. Радикально исправлять формулировки мне не пришлось, но три из них по предложениям пользователей я уточнил.

Резюме

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

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

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

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

Постскриптум. Цена вопроса

Исследование софта заняло 20 часов: скачать, установить, зарегистрировать, проверить все режимы работы, найти ограничения, всё непонятное — выпытать у разработчика. Картинки заняли 10 часов: скриншоты сделать, недостающее отрисовать и поправить столько раз, сколько потребуется. Буллит для выделения комментариев, например, удался с четвёртой итерации. Два осмысленных и проверенных текста общим объёмом 28 тысяч знаков заняли 40 часов. Вёрстка — 15 часов. Правки, шлифовка, полировка, и шабрение текста — в совокупности ещё 20 часов. Итого 105 часов учтённого рабочего времени, и какое-то количество неучтённого.

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