Разработать руководство пользователя для программного продукта

Писать руководство пользователя по шаблону. Удобно? Удобно

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

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

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

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

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

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

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

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

В связи с этим, мы сами создали готовые образцы и костяки шаблонных проектов в программе. Что входит в нашу базу:

• Руководство пользователя программного обеспечения.

• Руководство пользователя web-сервиса.

• Корпоративная база знаний компании.

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

Вы бережете своё время.

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

Вы сосредотачиваете внимание на вашей программе, а не на создании файл-справки

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

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

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

 Адаптация шаблонов и образцов под ваш проект.

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

О шаблонах

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

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

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

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

Особые случаи. Здесь нужно рассказать пользователю про то, какие трудности могут возникнуть и как их решить, выделить часто задаваемые вопросы и дать на них самый доступный ответ. Подразделы: «FAQ» и «Устранение типовых проблем»

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

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

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

Простое пошаговое руководство

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

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

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

Причины и преимущества создания руководства пользователя

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

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

Создание надлежащих руководств пользователя ограничивает юридическую ответственность продукции:

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

Создание хороших руководств пользователя экономит время:

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

Обучение клиентов использованию ваших продуктов:

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

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

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_jripxf4mYymO4f3xy/boo_occBcYZBFuyefSBLr/fe45270c-c55d-dab5-f45c-363cc455ecb821.png)

Итак, чтобы начать создавать руководство пользователя, необходимо понять, какую проблему вы пытаетесь решить для конкретного клиента. Создание руководства пользователя для всего обо всем превращает его в непонятную кашу, которую не поймет никто, включая целевую аудиторию. Если вы посмотрите на некоторые из лучших примеров руководств пользователя в Интернете, написанных такими компаниями-суперзвездами, как Stripe или Slack. Вы заметите определенную закономерность.

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

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

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

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

Давайте рассмотрим приведенное выше руководство по управлению книгой и определим несколько пунктов

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

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

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

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

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

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

Теперь давайте приступим к написанию первого руководства пользователя с помощью Docsie, это делается с помощью Docsies «Book».

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

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

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

Статьи очень легко создавать; просто введите заголовок. В данном случае это «Что такое Docsie», но вы можете ввести любое название для вашего руководства пользователя.

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_w2Fo0BuxXtGjFQuzx/boo_occBcYZBFuyefSBLr/42e5df8b-db8e-ec6a-6a70-dc0420c427376.png)

Чтобы создать подразделы в руководстве пользователя, которые будут отображаться как 1.1, 1.2…ext, все, что вам нужно сделать, это выбрать местоположение текста и установить текст как «Заголовок», что делается нажатием на H во вкладке редактора.

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_OCwuils7ezubiAv8a/boo_occBcYZBFuyefSBLr/1dd88460-f856-79c7-96a9-e43c31fd5f217.png)

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

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

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

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

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

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

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

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

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

1. Назначение
программы.

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

2. Условия
выполнения программы.

Минимальные
системные требования для успешного
выполнения программного продукта
«Калькулятор комплектующих ПК»:

– операционная
система: Windows XP;

– оперативная
память: 256 Мб;

– процессор: Intel
Celeron с тактовой частотой 233 МГц;

– видеоадаптер: видеокарта
с поддержкой DIRECTX 9;

– свободное
место на жестком диске: 20 Мб.

3. Выполнение
программы.

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

Рисунок
3.9 – Главная форма программы

«Калькулятор
комплектующих ПК»

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

Главное
меню содержит следующие
пункты: «Файл» – «Выход»;
«Действия» – «Фильтр», «Сумма»,
«Вставить в БД»; «Компоненты» –«Процессор»,
«Видеокарта», «Материнская плата»,
«Оперативная память», «Жесткий диск и
SSD»;
«Помощь» – «Справка о программе».

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

Рисунок
3.10 – Панель быстрых кнопок

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

Рисунок
3.11 – Вкладки с комплектующими компьютера

Список
текстовых полей содержит названия
выбранных комплектующих компьютера.
Каждое текстовое поле закреплено за
определенным комплектующим компьютера.
Внешний вид текстовых полей с названиями
комплектующих представлен на рисунке
3.12.

Рисунок
3.12 – Текстовые поля с названиями
комплектующих

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

Рисунок
3.13 – Панель состояния с подробными
подсказками

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

Рисунок
3.14 – Выделение синим цветом выбранной
комплектующей

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

Рисунок
3.15 – Название и цена выбранной
комплектующей компьютера

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

Рисунок
3.16 – Выбор параметров для поиска из
выпадающих списков

После
того, как выбраны параметры для поиска,
нужно нажать либо на кнопку «Фильтр»,
расположенную на панели быстрых кнопок,
либо нажать сочетание клавиш «Shift+F»,
либо зайти в раздел главного меню
«Действия» и выбрать пункт «Фильтр»
для того, чтобы был выполнен поиск
комплектующей по выбранным параметрам.

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

Рисунок
3.17 – Результат работы программы

«Калькулятор
комплектующих ПК»

4. Сообщения
пользователю.

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

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

– диалоговое
окно при выходе из программы;

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

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

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

ЗАКЛЮЧЕНИЕ

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

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

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

В
ходе выполнения выпускной квалификационной
работы были выполнены все поставленные
задачи:

1. Разработана
структура учебно-методического комплекса
по дисциплине «Разработка программных
приложений».

2. Разработана
рабочая программа, которая содержит
основные сведения по дисциплине
«Разработка программных приложений».

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

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

5. Разработан
макет для электронного учебно-методического
комплекса по дисциплине «Разработка
программных приложений».

6. Сверстан
макет для электронного учебно-методического
комплекса по дисциплине «Разработка
программных приложений».

7. Приведены
результаты проделанной работы, а именно:

– представлены
содержания разделов по дисциплине
«Разработка программных приложений»;

– представлены
содержания лабораторных работ по
дисциплине «Разработка программных
приложений»;

– представлены
веб-страницы электронного учебно-методического
комплекса по дисциплине «Разработка
программных приложений».

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

СПИСОК
ЛИТЕРАТУРЫ

1. Рудаков
А.В., Федорова Г.Н. Технология разработки
программных продуктов. Практикум. –
М.: Академия, 2012. – 192 с.

2. Лешек
Мацяшек. Практическая программная
инженерия на основе учебного примера.
– М.: Бином. Лаборатория знаний, 2012. –
956 с.

3. Орлов
С.А. Прогаммная инженерия. Учебник для
вузов. – СПб.: Питер, 2016. – 640 с.

4. Гагарина
Л.Г. Разработка и эксплуатация
автоматизированных информационных
систем. Учебное пособие. – М.: Инфра-М,
2015. – 384 с.

5. Алан
Купер, Роберт Рейман, Дэвид Кронин и
Кристофер Носсел. Интерфейс. Основы
проектирования взаимодействия. – СПб.:
Питер, 2017. – 720 с.

6. Тео
Мандел. Разработка пользовательского
интерфейса. – М.: Книга по Требованию,
2001. – 410 с.

7. Джеф
Раскин.
Интерфейс. Новые направления в
проектировании компьютерных систем. –
СПб.: Символ-Плюс, 2007. – 272 с.

8. Алфимцев
А.Н. 25
упражнений по юзабилити. – Саарбрюккен:
LAP Lambert Academic Publishing, 2014. – 108 с.

9. Макаровских
Т.А. Документирование программного
обеспечения. В помощь техническому
писателю. Учебное пособие. – М.: Ленанд,
2015. – 266 с.

10. Глаголев
В.А. Разработка технической документации.
Руководство для технических писателей
и локализаторов ПО. – СПб.: Питер, 2008. –
192 с.

11. Фленов
М.Е. Библия Delphi.
– СПб.: БХВ-Петербург, 2011. – 688 с.

12. Дарахвелидзе
П.Г., Марков Е.П. Программирование в
Delphi
7. – СПб.:
БХВ-Петербург, 2003. – 784 с.

13. Хоменко
А.Д., Гофман В.Э., Мещеряков Е.В. Delphi
7. – СПб.:
БХВ-Петербург, 2010. – 1136 с.

14. Шкрыль
А.А. Разработка клиент-серверных
приложений в Delphi. – СПб.: БХВ-Петербург,
2006. – 480 с.

15. Кириллов
В.В., Громов Г.Ю. Введение в реляционные
базы данных. – СПб.: БХВ-Петербург, 2009.
– 464 с.

16. Хоменко
А.Д., Гофман В.Э. Работа с базами данных
в Delphi. – СПб.: БХВ-Петербург, 2005. – 640 с.

17. Осипов
Д.Л. Базы данных и Delphi. Теория и практика.
– СПб.: БХВ-Петербург, 2011. – 752 с.

18. Астахова
И.Ф., Мельников В.М., Толстобров А.П.,
Фертиков В.В. СУБД: язык SQL в примерах и
задачах. – М.: Физматлит, 2009. – 168 с.

19. Маркин
А.В. Построение запросов и программирование
на SQL. Учебное пособие. – М.: Диалог-Мифи,
2014. – 384 с.

20. Дунаев
В.В. Базы данных. Язык SQL. – СПб.:
БХВ-Петербург, 2006. – 288 с.

21. Кисленко
Н.П. HTML.
Самое необходимое. – СПб.: БХВ-Петербург,
2008. – 352 с.

22. Петюшкин
А.В. HTML
в
Web-дизайне.
– СПб.: БХВ-Петербург, 2004. – 400 с.

23. Луис
Лазарис. CSS.
Быстрый старт. – М.: Эксмо, 2014. – 192 с.

24. Джон
Дакетт. HTML
и CSS.
Разработка и дизайн веб-сайтов. – М.:
Эксмо, 2013. – 480 с.

25. Захарова
И.Г. Информационные технологии в
образовании. – М.: Академия, 2013. – 192 с.

26. Федеральные
государственные образовательные
стандарты высшего профессионального
образования по направлениям подготовки
бакалавриата. URL: http://fgosvo.ru/fgosvpo/7/6/1
(дата обращения
–
20.03.2017).

27. ГОСТ
Р 55751-2013. Информационно-коммуникационные
технологии в образовании. Электронные
учебно-методические комплексы. Требования
и характеристики. – М.: Стандартинформ,
2014. – 11 с.

28. Шалкина
Т.Н., Запорожко В.В., Рычкова А.А. Электронные
учебно-методические комплексы:
проектирование, дизайн, инструментальные
средства. –
Оренбург: ГОУ
ОГУ,
2008.
– 160
с.

29. Фреймворк
Bootstrap
| ИТ Шеф.
URL: https://itchief.ru/lessons/bootstrap-3
(дата
обращения – 28.03.2017).

30. НОУ
ИНТУИТ | Лекция | Создание
справочной системы.
HTML
Help Workshop.
URL: http://www.intuit.ru/studies/courses/13745/1221/lecture/23323
(дата обращения – 13.05.2017).

Автор: Виктор Амосов, аналитик компании Индиго Байт, которая разрабатывает программу для управления технической документацией.

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

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

Советы по созданию пользовательской документации

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

Правила качественной документации, описанные в этой статье, основываются на десяти основных принципах юзабилити в дизайне, разработанных Jakob Nielsen и Rolf Molich в 1990 году. Однако — мне пришлось переработать многие из них на основе собственного опыта по оценке качества документации.

1.  Поиск и навигация

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

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

2. Ориентирование

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

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

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

3. Решение задач

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

4. Обобщение задач

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

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

5. Диагностика ошибок и устранение их последствий.

Пользователя надо научить не бояться проблем и решать их.

Говорить о своих проблемах – лучше, чем умалчивать…

В каждой программы возможны баги… Вы знаете о них, но пока нет времени исправлять? Лучше напишите и предупредите пользователя. Следуя моему опыту, лучше «признать» ошибку и показать себя, возможно, не с лучшей стороны, чем промолчать и потом терять клиентов из-за их неоправданных ожиданий. Если у пользователя будет инструкция по ликвидации проблем – он вряд ли задумается о смене программы.

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

6. Соответствие между документацией и реальным миром с точки зрения терминов и концепций

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

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

7. Писательский минимализм

Следует избегать ненужной и иррелевантной информации. Каждый дополнительный блок информации в документации будет конкурировать за пользовательское внимание. Это осложнит пользователю поиск нужной информации.

8. Согласованность и стандарты.

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

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

9. Интеграция с программным продуктом.

Пользователю грустно видеть программу, в которой он не может открыть «файл-помощник»!

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

А вообще, документация должна быть многоформатной! Пользователь может читать документацию и не работая в программе, поэтому следует загрузить документацию на сайт, тем самым сделав online-справку. Также стоит разместить на сайте PDF версию документации, для случаев, если у пользователя нет доступа к интернету.

Мини-итог

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

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

Инструменты для быстрого создания руководства пользователя

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

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

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

Далее вы ознакомитесь с некоторыми возможностями программы для создания руководства пользователя – Dr.Explain.

1. Аннотирование

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

2. Шаблоны

Гораздо проще работать по образцу. Для этого в Dr.Explain есть шаблоны руководств пользователя. В них разделы уже частично заполнены текстовым и графическим контентом. В некоторых случаях писателю, работающему в шаблоне, нужно будет только вставить текст из разряда: название программы, имя компании или адрес технической поддержки. В программе на данный момент есть три шаблона – для ПО, для WEB-сервиса и для корпоративной базы знаний.

3. Многоформатность.

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

В Dr.Explain, имея текстовый документ, вы сможете:

— экспортировать его на сайт продукта в формате HTML, тем самым создать online-справку;

— сделать контекстно-зависимую справку в формате CHM для интеграции с ПО;

— экспортировать текст в формат PDF для создания «печатной» документации;

В программе множество функций для облегчения работы по написанию документации. Вы можете ознакомиться с ними по адресу: https://www.drexplain.ru/features/

Скачать Dr.Explain бесплатно можно по адресу: https://www.drexplain.ru/download/

Подытожим

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

Успешных вам разработок!

Обсудить в форуме