Как написать руководство пользователя программы или сайта — инструкции, советы, помощь, программное обеспечение
Журавлев Денис
Что такое руководство пользователя и для чего его создавать
Ежедневно создаются новые продукты, программы, сервисы и часто пользователям приходится несладко при освоении какой-нибудь сложной программы, поэтому каждому новому продукту желательно собственное руководство. Для чего?
Большинство людей не хочет разбираться с чем-то незнакомым без персонального, всегда доступного и понятного помощника. А именно им и является хорошее руководство пользователя.
Общие советы по созданию пользовательской документации
Перед тем как приступить к созданию руководства, нужно определиться с некоторыми важными моментами. Например, определить, для кого вы его пишете? Кто его будет читать — рядовые пользователи, для которых важны базовые функции продукта, или люди, которым нужны особые, нечасто используемые функции программы/сервиса.
После этого важно подумать о том:
- Где пользователь будет к нему обращаться: дома, на работе, в машине?
- Как часто он будет его просматривать?
- Насколько объективно сложен для понимания продукт?
Из этого можно сделать вывод, насколько интенсивно пользователь будет работать с документацией, а значит уже можно выбрать между сжатым «справочником» или объемным «путеводителем» Также важно, чтобы руководство писал профессионал, знающий продукт. Так что по возможности делегируйте написание техническому специалисту или аналитику, у которого есть полное представление о всех тонкостях продукта.
Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте — не сделает ли полное отсутствие терминов ваше руководство бесполезным?
Структура руководства пользователя
После того как вы ответили на предыдущие вопросы, создайте структуру руководства. У любого хорошего «путеводителя» хорошая и логичная структура. Начните с оглавления. Информативное содержание поможет читателю легко ориентироваться в документе.
В первом разделе желательно рассказать общую информацию о программе:
- Для чего создан продукт.
- Какие задачи он решает.
- Какие основные выгоды от использования для клиента.
В следующем разделе можно указать основные элементы пользовательского интерфейса. Пользователю будет трудно разобраться в софте, если он не поймёт для чего служат различные элементы интерфейса, или он не разберётся в основных режимах работы ПО. Опишите понятным языком предназначение экранов и окон.
Создайте раздел, где расскажете о наиболее эффективных способах применения продукта для решения типовых задач. Какие цели стоят перед клиентом, и как ваша программа/сервис помогает достичь их. Укажите информацию о том, как быстро и продуктивно пользоваться программой.
Ни одно руководство не обойдется без таких разделов как: «Частые вопросы» и «Устранение типовых проблем» В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.
Иногда технические писатели забывают о важном моменте в руководстве пользователя — контактная информация. Этот раздел поможет пользователям связаться с вами, даже если у них нет никаких вопросов и руководство полностью закрывает все их потребности. Клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Инструменты для быстрого создания руководства пользователя
Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в MS Word.
Одним из популярных инструментов для создания качественного руководства является программа Dr. Explain (https://www.drexplain.ru), в которой уже есть готовые шаблоны руководств пользователя с готовой структурой разделов и в которой удобно обновлять документацию, как бы часто эти обновления не происходили.
Видео-обзор основных возможностей программы Dr.Explain
Удобной особенностью инструмента является возможность экспортировать один и тот же документ в форматы: HTML, CHM, PDF. Простой и понятный интерфейс сам подскажет, как быстро просмотреть документ в различных форматах и настроить его под вывод в эти форматы.
Любой проект в Dr.Explain вы можете создать с нуля или импортировать уже существующую документацию, например из формата MS Word, HTML или CHM-файла, и буквально за несколько минут создать из нее онлайн-помощь, файл справки в формате CHM, или документ в формате PDF.
При создании руководства важно опираться на заранее составленный план. Дерево проекта в Dr.Explain поможет структурировать документ по вашему усмотрению. Вы можете добавлять, удалять перемещать разделы и переименовывать их. Для каждого раздела вы можете определить, в какой формат он будет экспортироваться. Также в работе удобно использовать статусы готовности разделов.
У программы свой собственный редактор, оптимизированный под работу со сложной документацией. Основные функции редактора вынесены в компактный тулбар. Это — управление стилем текста, форматирование абзацев, вставка ссылок, изображений, видео, таблиц и списков, а также вставка специальных объектов. Dr. Explain экономит время и силы своих пользователей. Разработчики документации часто сталкиваются с проблемой многократного использования одного и того же фрагмента текста и прибегают к очевидным решениям — «Ctrl+c», Ctrl+v». Dr.Explain предлагает решение по повторному использованию контента — текстовые переменные. Это решение экономит время, когда нужно много раз использовать один и тот же текст, особенно, который может периодически изменяться — например, версия документируемой системы.
Многие российские компании сталкиваются с тем, что руководство пользователя нужно писать согласно ГОСТ 19 и ГОСТ 34. Dr.Explain активирует поддержку требований ГОСТ фактически одним кликом. Программа автоматически сформирует структуру обязательных разделов и установит требуемые параметры страницы, стили абзацев, списков и заголовков.
Часто техническим писателям при документировании пользовательского интерфейса приходится снабжать изображения пояснительными выносками. Для таких случаев программа поддерживает специальные графические объекты — аннотированные экраны. Чаще всего аннотируются скриншоты программ и страниц веб-сайтов. Уникальной особенностью Dr.Explain является автоматическая аннотация изображений, получаемых при захвате экранов с окнами программ или сайтов. Программа анализирует структуру окон и добавляет пояснительные выноски ко всем значимым элементам.
Кроме того, Dr.Explain позволяет нескольким авторам одновременно работать над проектом с использованием сервиса www.tiwri.com, учетную запись на котором можно создать бесплатно за пару минут. При внесении правок одним автором сервис блокирует редактируемые разделы проекта для изменения другими авторами. По окончании редактирования изменения отправляются на сервер, и блокировка снимается. Так несколько человек могут одновременно работать над различными разделами проекта без риска помешать друг другу.
Попробовать режим многопользовательской работы в Dr.Explain можно даже с бесплатной лицензией. Вы можете создать общий проект и полноценно работать с ним в многопользовательском режиме до семи дней.
Почему компании выбирают Dr.Explain для создания руководств пользователя
Павел Свиридов, профессиональный военный, полковник, создатель астрологической системы «Вега Матрица»
«Только программа Dr.Explain обладала всеми необходимыми возможностями. А главное — она давала простор для творчества. Можно было выбрать цветовую гамму, вид и форму служебных элементов, настраиваемые шаблоны. Это позволило мне сохранить стилевое единство документации и самой программы. Ну, и конечно, полуавтоматическая обработка материала существенно облегчает и ускоряет работу по созданию хелпа.
Обучение работе в Dr.Explain было наглядным и сделано возможностями самой программы, что безусловно повлияло на мой выбор в ее пользу».
Прочитать полный кейс компании «Вега Матрица вы можете перейдя по ссылке
Наталья Обухова, бизнес-аналитик компании CRM Expert
«По классике жанра был пилотный проект на двух фаворитах (Dr.Explain и HelpNDoc) и муки выбора.
Через неделю справка была полностью готова. Конечно, если мы набивали ее «с нуля», за это время мы бы не успели. Мы просто конвертировали все бумажные инструкции во внутренний формат программ, изменили каталогизацию и организовали систему гиперссылок.
Сначала фаворитом выбора была другая система, но решающим фактором в пользу Dr.Explain стал возглас человека, выполняющего основную часть работы по переносу текста: «Вжух! И вся структура документа перенеслась в файл справки». Функция импорта в Dr.Explain отработала на ура и сэкономила кучу времени.
Также очень подкупил дизайн веб-справки, который формируется Dr.Explain, и красивый способ организации подписей к окнам нашей системы. В Dr.Explain это называется «Аннотирование экрана».
Возможность установки статуса раздела тоже оказалась очень удобной, особенно, после импорта старой версии справки легко отслеживать, какие разделы требуют обновления, в каких еще ведутся изменения, а какие уже обновлены и актуальны».
Прочитать полный кейс компании CRM Expert
Николай Вальковец, разработчик компании 2V
«Мы значительно сократили время работы техподдержки с новыми клиентами на этапе подключения. Раньше требовалось проводить онлайн презентации и видео конференции для новых клиентов, объясняя особенности программы. Сейчас же, один раз постаравшись максимально подробно всё описать, мы избавили себя и нашу техподдержку от этой работы. Нам импонирует простота программы и скорость работы. Можно быстро редактировать, добавить новые пункты в документацию, сохранить в формате HTML и выложить на сайт».
Прочитать кейс компании V2
Подытожим
Создание и написание хорошей пользовательской документации — это труд, который требует много времени и усилий. Но если успешно справиться с задачей, можно навсегда получить лояльных и довольных клиентов. Не забывайте о том, что недовольство от некачественного руководства может быть спроецировано пользователем на сам продукт и повлиять на дальнейшие решения о его выборе. Пользовательская документация должна стать персональным и незаменимым помощником. Используя Dr. Explain, вы сможете быстро создать качественное руководство пользователя, которое будет помогать пользователям разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.
Скачать Dr.Explain с неограниченной по срокам возможностью бесплатной работы можно по адресу: https://www.drexplain.ru/download/
Успешных вам разработок!
Смотрите также
- Dr.Explain — инструмент для создания мобильной версии пользовательской документации к программным продуктам
- Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний — бесплатные шаблоны и примеры пользовательской документации
Писать руководство пользователя по шаблону. Удобно? Удобно
Время на прочтение
4 мин
Количество просмотров 4.7K
Команда, разрабатывающая софт для создания пользовательской документации, делится лайфхаками на тему написания идеальной пользовательской документации для тех, кто далёк от написания руководств к программе.
Для чего мы сами конструируем некоммерческие образцы документации и инструкций для пользователей
Наш проект существует и развивается уже долгое время, практически шестнадцать лет, если быть точнее. За этот срок была сформирована определенная база, где собраны самые актуальные и насущные вопросы, которые возникают перед людьми, создающими справочные элементы к своему проекту.
Ведя диалог с нашими клиентами, мы смогли выделить их потребности и понять основную «боль». Если обобщить, основная проблема заключалась в том, что ни одна программа для создания файл-справок и инструкций не могла выполнить самую нудную, энергозатратную часть проекта — само разрабатывание и оформление этой пользовательской документации
Даже имея осознание того, что файл-справка — неотъемлемый и действительно полезный элемент для пользователя, очень редко возникает мотивация оформить его грамотно и качественно. Еще реже желание возникает, когда в написании пользовательской документации нет опыта или специалистов, которые бы этот опыт имели. Обычно, эта обязанность с легкой руки падает на плечи самих создателей программы, людей, занимающихся тестированием, аналитикой, специалистам поддержки или даже руководителей компании, которые тоже не совсем понимают, как грамотно создать что-то подобное.
Отсюда вытекает еще одна загвоздка. Люди, у которых нет опыта и в принципе понимания, как начать и что туда вносить, просто не знают, как создать качественное руководство для пользователей. В таких случаях большинство следует привычному пути: загуглить определение и найти готовый шаблон.
И с какой-то стороны, это разумно. Мы достаточно часто сталкиваемся с такими запросами, пользователи просят у нас пошаговое руководство или хотя бы костяк готовой инструкции.
Так вышло, что потребности наших клиентов практически на сто процентов входят в нашу экспертную сферу. И мы приняли решение по возможности помочь всем, кто хочет (или вынужден) заниматься созданием файл-справок и инструкций к своему продукту и предоставить возможность получить образцы, которые могут послужить базой и легко быть адаптированными под конкретный запрос.
В связи с этим, мы сами создали готовые образцы и костяки шаблонных проектов в программе. Что входит в нашу базу:
-
Руководство пользователя программного обеспечения.
-
Руководство пользователя web-сервиса.
-
Корпоративная база знаний компании.
В чем удобство создания руководства пользователя по образцу
Вы бережете своё время.
Адаптируя уже созданный образец под свой продукт, вы не тратите время на создание основы с нуля, вам не нужно тратить время, чтобы найти мастер-класс о том, как правильно это сделать. Используя готовый шаблон документации, вы значительно экономите время на создание структуры проекта с нуля и на поиск и изучение информации о том, как это делается.
Вы сосредотачиваете внимание на вашей программе, а не на создании файл-справки
В шаблоне уже есть текстовые и графические вставки, вы можете сами добавлять нужный контент в предложенные места и не продумывать вариант оформления.
Наглядность.
Все образцы и костяки инструкций для пользователя изначально настроенные с динамическими стилями оформления, которые помогут вам быстрее освоиться и разобраться, как можно использовать это для быстрого выполнения своей цели.
Адаптация шаблонов и образцов под ваш проект.
Всё, что находится в шаблонах, можно назвать нашим советом, который был создан на основе многолетнего опыта в данной сфере и выработанной экспертностью. Абсолютно всё в этих шаблонах может быть подвержено адаптации, так как для пользовательской документации нет жестких стандартов, она должна быть выстроена персонально под ваш продукт.
О шаблонах
За 15 лет мы смогли подвергнуть аналитике более сотни разных файл-справок, инструкций и технических документаций, что дало нам возможность сделать вывод и определить шаблонные разделы, которые могут быть применены к огромному количеству программ, после чего мы интегрировали их в наши образцы. Давайте немного подробнее поговорим о структуре.
Обзор возможностей программ. Здесь идет краткое содержание сути вашего продукта. Где вы рассказываете о том, для чего нужна ваша программа. Какие боли и потребности она удовлетворяет, на что способна.
Пользовательский интерфейс. Здесь вы можете наглядно показать вашему клиенту интерфейс, ознакомить его со всеми режимами, дополнительными кнопками и.т.д. Если пользователь может персонализировать интерфейс под себя, об этом тоже лучше указать именно в этом разделе.
Типовые задачи. Здесь нужно максимально подробно познакомить пользователя со всеми основными возможностями программы и детально описать ряд задач и вопросов, которые клиент сможет решить с её помощью. В нашем образце этот блок сформирован из двух подразделов. В подразделе «Примеры использования» лучше всего рассказать пользователю, как ваш продукт будет решать его вопросы и задачи. Если обобщить, то в этом подразделе вы рассказываете про клишированные проблемы, с которыми сталкивается большинство пользователей. В подразделе «Лучшие практики» лучше разместить максимально полезную информацию о том, как упростить свою работу в программе и как пользоваться ей максимально эффективно.
Особые случаи. Здесь нужно рассказать пользователю про то, какие трудности могут возникнуть и как их решить, выделить часто задаваемые вопросы и дать на них самый доступный ответ. Подразделы: «FAQ» и «Устранение типовых проблем»
Вспомогательная и юридическая информация. Здесь вы размещаете информацию о компании, размещаете контактные данные тех.поддержки, информацию о сотрудничестве, сайт, а также лицензионные соглашения.
Названия проекта публиковать не будем, Хабр ругается.
P.S. Мы будем рады, если наши образцы помогут вам закрыть вопрос и успешно реализовать документацию в своем проекте.
Многие согласятся, что написание документации пользователя к ПО или сервису нелегкая задача.
Разработчики часто откладывают создание подобной документации в долгий ящик, поскольку считают ее трудоемкой, требующей дополнительных расходов или прямо-таки скучной.
Нужно досконально изучить программу, предсказать, с какими трудностями могут столкнуться пользователи, описать все возможности продукта, создать логичную структуру, добавить достаточно скриншотов и пояснений. И когда все будет готово – выложить документацию на сайт продукта и/или внедрить справку в ПО.
Часто подобную документацию пишут в текстовых редакторах, но это значительно усложняет и без того скучный процесс. Специализированное ПО имеет множество функций, упрощающих процесс создания руководства. Например, возможность структурировать будущую документацию, создавать разделы, делать пояснения на скриншотах, экспортировать контент в различные форматы (HTML, CHM, PDF) и многое другое.
Если вам не нравится процесс документирования продукта, над которым вы работаете, этот обзор для вас.
В нем мы расскажем, про лучшие инструменты для создания пользовательской документации на рынке, которые превратят эту тяжелую и, казалось бы, невыполнимую задачу – в легкую прогулку.
Но разве техническая поддержка не может стать заменой документации?
— Скорее нет, чем да. Есть внушительное число пользователей, которые с радостью обратятся к справочной документации, нежели будут писать в поддержку, ждать ответа, общаться с людьми.
— Поддержка может подвести. Случайно или из-за некомпетентности сотрудников. Грубость техподдержки – тоже нередкое явление.
Также, техподдержку могут просто завалить вопросами, и она не будет успевать отвечать.
Подобные случаи негативно сказываются на репутации и лучше заранее застраховаться. Например – создать руководство пользователя.
Сегодня мы подобрали для вас 5 лучших программ и сервисов для создания пользовательской документации, которые, по нашему мнению, лучше всего подходят для своей роли.
1. Dr.Explain
Операционная система – Windows
Цена – от 10 000 рублей в год или 16000 рублей навсегда в рамках старшей версии (есть бесплатная версия)
Dr.Explain – одна из немногих программ, которая автоматизирует процесс создания документации пользователя. При написании документации перед писателем стоит задача наглядно показать, как все работает и где что находится. Для этого в руководства вставляют скриншоты с пояснениями к элементам интерфейса программы. В Dr.Explain есть специальный инструмент, который выделяет все важные элементы на скриншоте, например, кнопки или поля, и добавляет к ним аннотации (выноски) с пояснениями. Все что останется сделать писателю – снабдить их описаниями.
Второе, что бросается в глаза, когда изучаешь возможности программы — встроенные шаблоны документации. Всегда проще работать по образцу, смотреть на пример документации, дополнять и видоизменять под свой продукт. Именно это и предлагает Dr.Explain. В программе существует три шаблона документации: руководство пользователя для ПО, руководство пользователя для web-сервиса и шаблон корпоративной базы знаний.
Как бы хорошо программа не помогала писать документацию, конечная цель – это публикация контента на сайте продукта и интеграция его в продукт, чтобы пользователи могли прочитать ваше руководство. Dr.Explain позволяет экспортировать ваш проект в популярные форматы: HTML – для сайта, CHM – для встроенной в ПО справки и PDF.
Dr.Explain позволяет работать в команде через облачный сервис или локальный сервер. В программе можно задавать разделам «степень готовности». Так вы сможете контролировать процесс написания справки.
В программе имеется удобный и продуманный WYSIWYG (What You See Is What You Get, «что видишь, то и получишь») редактор, возможность настраивать стиль вашей документации, возможность настроить контекстно-зависимую справку и что немаловажно – в ней есть русский интерфейс, так как Dr.Explain – проект отечественной команды разработчиков и продукт включен в реестр отечественного ПО.
+ Большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя (аннотирование скриншотов, шаблоны документации и т.д.)
+ Русский интерфейс
+ Простая оплата для российских пользователей
Минусы:
— Отсутствие веб-интерфейса
— Отсутствие версии для Mac и Linux
— Нет вывода в ePub, markdown и другие специфические форматы
2. HelpnDoc
Операционная система – Windows
Цена – от $99 в год (есть бесплатная версия)
Главный плюс HelpnDoc – возможность экспорта в невообразимое множество форматов, тем самым возможность создания мультиформатной документации.
Создаёте документацию для мобильного приложения? Вашим пользователям нужно читать документацию с электронной книги? Нужно создать документацию к продукту на Linux, Ubutu, UNIX? Эта программа поможет.
Мощная система медиабиблиотеки. Все медиа-элементы, такие как изображения, видео, документы, фрагменты HTML-кода, управляются библиотекой: эти медиа-элементы можно использовать повторно много раз.
Нужно изменить одну картинку, а она размещена в документации десятки раз? Просто обновите элемент библиотеки, и он будет распространен на все темы, использующие его.
Благодаря редактору сценариев можно легко автоматизировать повторяющиеся задачи и сфокусировать своё внимание на сложных. Вам нужно изменить порядок тем? Заменить все элементы библиотеки? Запустите редактор сценариев, введите несколько инструкций, нажмите «Выполнить», после чего часть рутинной работы будет выполнена автоматически.
HelpnDoc анализирует написанную документацию и может показать вам неработающие ссылки, ссылки с ошибками, отсутствующие или дублирующие элементы мультимедиа. Все подобные ошибки можно увидеть в одном месте (анализаторе) и сразу же приступить к их устранению.
Плюсы:
+ Возможность создания мультиформатной документации.
+ «Сценарии» значительно упрощают и ускоряют процесс написания руководства
+ Умный анализ и проверка вашего проекта.
Минусы:
— нет русского интерфейса, и если вы будете создавать руководство на русском языке, то некоторые возможности по анализу и проверке будут недоступны.
— сравнительно сложный пользовательский интерфейс.
— сложность с оплатой лицензий для российских пользователей.
3. ClickHelp
Операционная система – любая.
Цена – от $50 в месяц.
ClickHelp в отличие от двух предыдущих – не программа, это web-сервис для создания документации.
Сервис полезен для продуктов, которые хотят выйти на международный рынок. В ClickHelp существует возможность перевода вашего руководства на любой язык, при помощи Google, конечно. Что немаловажно, изменяя исходный текст, изменения будут отображаться во всех переведенных вариантах на этих же языках.
Представьте, что пользователи открывают руководство и пытаются найти что-то по определенной теме. Вводят в поиск термин и им выдается все множество совпадений, которые только есть.
Специально для этого в ClickHelp есть ряд функций, чтобы клиенты всегда могли найти ответ на свой вопрос:
— Система полнотекстового поиска, в которой читатель можете осуществлять поиск по всему порталу документации или только по определенному набору руководств пользователя. Она обрабатывает формы слов и времена, чтобы читатели могли использовать естественный язык, учитывает близость терминов и другие факторы при ранжировании результатов.
— Система индексов. Если вы думаете, что пользователю все равно будет трудно найти какую-то информацию в вашей документации – система индексов или таксономий в ClickHelp решит эту проблему. Данная функция предназначена для того, чтобы сделать темы доступными для поиска по терминам, которые не находятся непосредственно в их содержании. Например, если в документации есть тема о SSL-шифровании, вы можете присвоить ей индексное ключевое слово «безопасность», и даже если в теме нет ни единого упоминания «безопасности» или каких-либо производных, она все равно будет доступны для поиска по этому термину.
В ClickHelp можно работать в команде. Сервис позволяет следить за процессом разработки, оставлять комментарии, от которых уведомления будут приходить на почту, раздавать роли.
Плюсы:
+ Возможность работы в команде через веб-интерфейс и отслеживание результатов.
+ Поиск по документации.
+ Автоматический перевод документации на любые языки.
Минусы:
— Достаточно сложный в освоении продукт и интерфейс только английский, что усложнит задачу понимания сервиса и его функций.
— Высокая стоимость лицензии.
— Нет возможности работать в offline-режиме.
4. HelpSmith
Операционная система – Windows
Цена – от $199.
Одной из основных возможностей HelpSmith является создание нескольких форматов справки из единого источника. Таким образом, имея один исходный текст, вы можете экспортировать его в HTML для создания веб-справки, в PDF, MS Word, а также в формат ePub для электронных книг.
Программа имеет встроенный инструмент по работе с изображениями, чем-то напоминающий Dr.Explain. В нем вы можете редактировать изображения и добавлять к ним аннотации. Кроме того, всё медиа, которое вы используете в проекте, хранится в едином репозитории, что упрощает процесс обновления и сохранения изображений в документации.
Для опытных технических писателей HelpSmith предоставляет гибкие возможности условной компиляции, позволяющие создавать разные версии одного и того же файла справки для разных аудиторий пользователей.
Следует отметить, что файл справки или систему веб-справки можно легко интегрировать в ваше приложение или веб-сайт, поэтому вы можете предоставлять контекстно-зависимую справку, экспортируя список тем в файл заголовка, совместимый с вашей IDE, такой как C #, VB .NET, Delphi, C++, MS Office VBA.
Также, из необычных дополнительных функций HelpSmith является — «Подсветка синтаксиса» — для создания документации API, файлов справки с примерами кода и любых других видов документации, содержащей программный код, написанный на различных языках программирования.
Плюсы:
+ большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя
+ простота и удобства использования.
Минусы:
— Отсутствие простого механизма многопользовательской работы
— Интерфейс и материалы на английском языке
— Отсутствие Mac и веб-версии
5. MarkdownPad
Операционная система – Windows
Цена – бесплатно. Есть платная версия – $15.
MarkdownPad — известный редактор Markdown для Windows. Он прост и так же удобен в использовании, как Microsoft Word, и поставляется с редактором WYSIWYG, поэтому вам даже не нужно знать Markdown.
MarkdownPad отлично подходит, если вам нужно быстро выложить документацию на сайт, создать веб-сайт и все, что связано с HTML. Вы можете в любой момент посмотреть, как будет выглядеть ваша документация, используя предварительный просмотр.
Все настраивается под себя. Вы можете воспользоваться широкими возможностями настройки, такими как макеты, шрифты и размеры. Вы также можете включить свои собственные таблицы стилей CSS. Он поставляется со встроенным в платформу редактором CSS, поэтому вы можете стилизовать текст по своему вкусу.
Плюсы:
+ Очень удобная и в целом простая программа, что даже не получилось написать про неё больше 3 абзацев
+ Стоимость.
Минусы:
— Малый функционал, по сравнению с большинством подобных инструментов.
Заключение
Пользовательская документация – незаменимый инструмент, позволяющий укреплять лояльность пользователей, прикрывать техподдержку, повышать SEO-факторы продукта. Кроме того, наличие технической документации — один из основных критериев допуска в Реестр отечественного ПО Минцифра России.
Создание действительно качественной документации, которая будет приносить пользу – тяжелая задача, на которую придется потратить немало времени и сил. Специально для упрощения этой задачи и были созданы программы для написания документации, а мы постарались предоставить вам список лучших таких инструментов.
Примеры и рекомендации удобных инструкций
Снова здравствуй, уважаемый хабралюд!
В продолжении своего поста решил написать, как лучше всего создавать инструкции для пользователей и администраторов.
Всем, кому интересно, прошу под хабракат.
Принцип Keep It Simple Stupid хорошо известен в программировании, но почему-то его редко используют для написания инструкций и руководящих документов, предпочитая растекаться мыслею по древу. В 70% ситуаций эта документация необходима только для того, что бы отмахаться от наших бодрых регуляторов, но при этом забывают, что с этой документацией придётся работать, причём не всегда технически подкованным и грамотным в области информационной безопасности людям.
Для начала напишу несколько правил, которые помогут создать рабочий и удобный документ:
1. Старайтесь разделять инструкцию для пользователей от инструкции для администраторов и офицеров безопасности. причём первые не должны содержать ссылок на вторые (они могут содержать отсылки друг к другу).
2. Делайте пошаговые инструкции, вида «взял и сделал». То есть инструкции должны описывать алгоритм действий того, на кого она направлена.
3. Каждый пункт описывайте, как отдельное действие с обязательным указанием ответственного и контактами, если они необходимы.
4. Для большей наглядности можете дополнительно нарисовать в инструкцию блок-схему действий. Это поможет пользователю наглядно понять и оценить действия, так же и вам доступно объяснить алгоритм при обучении.
5. Психологический момент — инструкция будет плохо выполняться и работать, если пользователям понятно и доступно не объяснят алгоритм на пальцах и примерах. Поэтому — НЕ ЗАБЫВАЙТЕ ПРО ОБУЧЕНИЕ!
Пример инструкции для пользователей
Ниже приведен пример инструкции по заведению аккаунта пользователя в корпоративной сети. 
Clear screen/clear desk
Специфика российских организаций, работающих с советских времен и таких же умудренных опытом сотрудников такова, что у них, как правило, стол завален бумагами. Компьютер порой не выключается и не блокируется, даже когда уходят домой. Недавно лично видел, проходя поздно вечером мимо одного муниципального предприятия, как за открытыми жалюзи в закрытом на замок здании горел монитор с открытым на нём вордовским документом.
Пользователи порой не догадываются о возможных непреднамеренных утечках информации. Пускай она не конфиденциальна, возможно она только для внутреннего пользования. Но это даёт понимание, что в этой организации не заботятся о своей безопасности и могут так поступить с конфиденциалкой. А так же возможно там будет информация, ещё не отнесенная к закрытой, но уже существующая во внутреннем обороте организации.
Хорошим примером из лучших практик здесь является политики чистого стола и чистого экрана. Их можно описать так же, как я приводил пример ранее, но это будет выглядеть немного глупо, так как действия там простейшие. Лучше просто сделать набором правил:
На этом завершаю примеры и рекомендации. Серию подобных постов я продолжу, если будет интерес.
Источник
ocnova.ru
Как написать руководство пользователя
Ответить Аналитика Сентябрь 23rd, 2010 Аналайзер
На личном примере убедилась, что писать руководства пользователя – не такая уж и простая задача… Особенно если не знаешь программный продукт по которому его нужно составить!
Так как же написать руководство пользователя?
Не так давно, я устроилась на новую работу в компанию, занимающуюся разработкой и внедрением программного продукта… все бы хорошо.. но я споткнулась уже на первом своем задании..
Передо мной поставили задачу написать руководство пользователя по программе, которую я даже никогда до этого не видела (кажется, что-то из бухгалтерского учета, в чем я не так уж и шибко разбираюсь). Никаких старых версий руководств пользователя, никаких примеров.. только я и программа.. В процессе работы я столкнулась с некоторыми подводными камнями, которые и попытаюсь описать в данной статье.
Казалось бы, что может быть сложного! Есть программа.. немного мозгового штурма – и все сделано. Конечно, самый идеальный вариант, это если руководство пользователя пишет сам разработчик «чуда-природы» или, по меньшей мере, пользователь, давно работающий в описываемой системе.
А что делать, если это не так?! Первым делом бежать к разработчику и хорошенько «сесть ему на шею», чтобы он «разжевал» свое «детище» от начала до самого предельного уровня. В таких случаях лучше представить себя «Почемучкой» и докапываться до самых мелочей. К сожалению, нервы программиста такого порыва не оценят! Но тут выбор прост, либо хорошее руководство, либо обмен любезностями и только…
В любом случае, нужно посмотреть на программу «со стороны» глазами первопроходца! Предварительно выделив функциональные модули, и модуль, который представляет наибольший интерес для конечного пользователя (его лучше всего описать мах подробно!), необходимо определить степень детализации проектируемого руководства. Обычно этот вопрос обсуждается с руководством организации –разработчика, но можно и на свое усмотрение.
По своему опыту, могу сказать, что при написании руководства пользователя лучше потратить немного времени на проектирование общей структуры пояснительной записки, чем потом писать для каждого функционального модуля отдельные руководства. Дело в том, что чем стандартизованней (структурированней) руководство, тем проще ориентироваться пользователю и описывать легче! При продуманной структуре описания вероятность «забыть» отобразить какой-то ключевой момент значительно снижается!
Еще есть такой хороший момент – это ГОСТы! Для описания руководств пользователя существует такой замечательный ГОСТ, как ГОСТ 19.505-79 (описание см. в разделе сайта).
Как написать руководство пользователя:
Основным ориентиром для написания руководства можно выделить следующее описание:
В качестве примера, могу предложить свою методику описания выполнения программы. В начале нужно проанализировать весь описываемый программный продукт и определить разбивку по отдельным модулям (разделам и т.п.).
Параллельно нужно определить функции меню, повторяющиеся наименования полей и другой функционал, которые стандартны по всему модулю, разделу программного продукта и т.д.
Далее формируем следующую структуру:
В раздел «Краткое описание» помещается краткое описание модулей А и В, а также описываются те повторяющиеся пункты меню, наименования полей и т.п., характерные для обоих модулей. Далее в описании самого модуля/подмодуля описывается краткий алгоритм работы с модулем/подмодулем (загрузка, просмотр, добавление, редактирование, удаление, формирование отчетов и т.д), после чего осуществляется более подробное описание всего функционала и всех имеющихся полей.. Иными словами все в деталях!
Описывается специфика полей, с какими операциями связано их заполнение, какие значения присваиваются автоматически, в каких случаях вообще отображаются поля, типы полей, все кнопочки, галочки.. В общем, тут можно описывать до бесконечности.
Если модуль содержит в себе подмодули, то лучше описать все в строгой последовательности.. Т.е. в начале описать сам модуль (от начала до конца), при этом сделать ссылку на соответствующий подмодуль, а ниже –подробно описать весь подмодуль! Получается достаточно красивая картинка! Пользователю не приходится перескакивать от одной части документа в другую и обратно..
И так описывается весь программный продукт. В концовке можно написать список используемых сокращений, употребленных при описании руководства пользователя.
Бесспорно, что данная методика носит обобщенный характер! Но из своего опыта могу сказать точно, очень удобна! Удобно пользователю, удобно разработчику руководства пользователя! Все довольны.. 😉
Но как говорится, на вкус и цвет товарища нет! Остается пожелать успешных разработок!
Источник
Корпоративные хранилища данных. Интеграция систем. Проектная документация.
РД 50-34.698-90 Руководство пользователя (пример оформления)
Ниже представлен пример (образец) документа «Руководство пользователя«, разработанного на основании методических указаний РД 50-34.698-90.
Данный документ формируется IT-специалистом, или функциональным специалистом, или техническим писателем в ходе разработки рабочей документации на систему и её части на стадии «Рабочая документация».
Для формирования руководства пользователя в качестве примера был взят инструмент Oracle Discoverer информационно-аналитической системы «Корпоративное хранилище данных».
Ниже приведен состав руководства пользователя в соответствии с ГОСТ. Внутри каждого из разделов кратко приведены требования к содержанию и текст примера заполнения (выделен вертикальной чертой).
Разделы руководства пользователя:
1. Введение
В разделе «Введение» указывают:
1.1. Область применения
Требования настоящего документа применяются при:
1.2. Краткое описание возможностей
Информационно-аналитическая система Корпоративное Хранилище Данных (ИАС КХД) предназначена для оптимизации технологии принятия тактических и стратегических управленческих решений конечными бизнес-пользователями на основе информации о всех аспектах финансово-хозяйственной деятельности Компании.
ИАС КХД предоставляет возможность работы с регламентированной и нерегламентированной отчетностью.
При работе с отчетностью используется инструмент пользователя Oracle Discoverer Plus, который предоставляет следующие возможности:
1.3. Уровень подготовки пользователя
Пользователь ИАС КХД должен иметь опыт работы с ОС MS Windows (95/98/NT/2000/XP), навык работы с ПО Internet Explorer, Oracle Discoverer, а также обладать следующими знаниями:
Квалификация пользователя должна позволять:
1.4. Перечень эксплуатационной документации, с которой необходимо ознакомиться пользователю
2. Назначение и условия применения Oracle Discoverer Plus
В разделе «Назначение и условия применения» указывают:
Oracle Discoverer Plus в составе ИАС КХД предназначен для автоматизации подготовки, настройки отчетных форм по показателям деятельности, а также для углубленного исследования данных на основе корпоративной информации хранилища данных.
Работа с Oracle Discoverer Plus в составе ИАС КХД возможна всегда, когда есть необходимость в получении информации для анализа, контроля, мониторинга и принятия решений на ее основе.
Работа с Oracle Discoverer Plus в составе ИАС КХД доступна всем пользователям с установленными правами доступа.
3. Подготовка к работе
В разделе «Подготовка к работе» указывают:
3.1. Состав и содержание дистрибутивного носителя данных
Для работы с ИАС КХД необходимо следующее программное обеспечение:
3.2. Порядок загрузки данных и программ
Перед началом работы с ИАС КХД на рабочем месте пользователя необходимо выполнить следующие действия:
3.3. Порядок проверки работоспособности
Для проверки доступности ИАС КХД с рабочего места пользователя необходимо выполнить следующие действия:
В случае если приложение Oracle Discoverer Plus не запускается, то следует обратиться в службу поддержки.
4. Описание операций
В разделе «Описание операций» указывают:
Для каждой операции обработки данных указывают:
В описании действий допускаются ссылки на файлы подсказок, размещенные на магнитных носителях.
4.1. Выполняемые функции и задачи
Oracle Discoverer Plus в составе ИАС КХД выполняет функции и задачи, приведенные в таблице ниже:
| Функции | Задачи | Описание |
|---|---|---|
| Обеспечивает многомерный анализа в табличной и графической формах | Визуализация отчетности | В ходе выполнения данной задачи пользователю системы предоставляется возможность работы с выбранным отчетом из состава преднастроенных. |
| Формирование табличных и графических форм отчетности | В ходе выполнения данной задачи пользователю системы предоставляется возможность формирования собственного отчета в табличном или графическом виде на базе преднастроенных компонентов. |
4.2. Описание операций технологического процесса обработки данных, необходимых для выполнения задач
Ниже приведено описание пользовательских операций для выполнения каждой из задач.
Задача: «Визуализация отчетности»
Операция 1: Регистрация на портале ИАС КХД
Условия, при соблюдении которых возможно выполнение операции:
На компьютере пользователя необходимо выполнить дополнительные настройки, приведенные в п. 3.2 настоящего документа.
Основные действия в требуемой последовательности:
Ресурсы, расходуемые на операцию:
Операция 2: Выбор отчета
Условия, при соблюдении которых возможно выполнение операции:
Успешная регистрация на Портале ИАС КХД.
Основные действия в требуемой последовательности:
1. В появившемся окне «Мастер создания рабочих книг» поставить точку напротив пункта «Открыть существующую рабочую книгу».
2. Выбрать нужную рабочую книгу и нажать кнопку «Откр.»:
После завершения работы с отчетом необходимо выбрать пункт меню «Файл», далее выбрать пункт «Закрыть».
Ресурсы, расходуемые на операцию:
Задача: «Формирование табличных и графических форм отчетности»
Заполняется по аналогии.
5. Аварийные ситуации
В разделе «Аварийные ситуации» указывают: 1. действия в случае несоблюдения условий выполнения технологического процесса, в том числе при длительных отказах технических средств; 2. действия по восстановлению программ и/или данных при отказе магнитных носителей или обнаружении ошибок в данных; 3. действия в случаях обнаружении несанкционированного вмешательства в данные; 4. действия в других аварийных ситуациях.
В случае возникновения ошибок при работе ИАС КХД, не описанных ниже в данном разделе, необходимо обращаться к сотруднику подразделения технической поддержки ДИТ (HelpDesk) либо к ответственному Администратору ИАС КХД.
| Класс ошибки | Ошибка | Описание ошибки | Требуемые действия пользователя при возникновении ошибки |
|---|---|---|---|
| Портал ИАС КХД | Сервер не найден. Невозможно отобразить страницу | Возможны проблемы с сетью или с доступом к порталу ИАС КХД. | Для устранения проблем с сетью обратиться к сотруднику подразделения технической поддержки (HelpDesk). В других случаях к администратору ИАС КХД. |
| Ошибка: Требуется ввести действительное имя пользователя | При регистрации на портале ИАС КХД не введено имя пользователя. | Ввести имя пользователя. | |
| Ошибка: Требуется ввести пароль для регистрации | При регистрации на портале ИАС КХД не введен пароль. | Ввести пароль. | |
| Ошибка: Сбой аутентификации. Повторите попытку | Неверно введено имя пользователя или пароль, либо такая учетная запись не зарегистрирована. | Нужно повторить ввод имени пользователя и пароля, однако после третей неудачной попытки регистрации учетная запись блокируется. Если учетная запись заблокирована, нужно обратиться к администратору ИАС КХД. | |
| Сбой в электропитании рабочей станции | Нет электропитания рабочей станции или произошел сбой в электропитании. | Рабочая станция выключилась или перезагрузилась. | Перезагрузить рабочую станцию. Проверить доступность сервера ИАС КХД по порту 80, выполнив следующие команды: — нажать кнопку «Пуск» — выбрать пункт «Выполнить» — в строке ввода набрать команду telnet ias_dwh.ru 80 — если открылось окно Telnet, значит соединение возможно. Повторить попытку подключения (входа) в ИАС КХД |
| Сбой локальной сети | Нет сетевого взаимодействия между рабочей станцией и сервером приложений ИАС КХД | Отсутствует возможность начала (продолжения) работы с ИАС КХД. Нет сетевого подключения к серверу ИАС КХД | Перезагрузить рабочую станцию. Проверить доступность сервера ИАС КХД по порту 80, выполнив следующие команды: — нажать кнопку «Пуск» — выбрать пункт «Выполнить» — в строке ввода набрать команду telnet ias_dwh.ru 80 — если открылось окно Telnet, значит соединение возможно. После восстановления работы локальной сети повторить попытку подключения (входа) в ИАС КХД. |
6. Рекомендации по освоению
В разделе «Рекомендации по освоению» указывают рекомендации по освоению и эксплуатации, включая описание контрольного примера, правила его запуска и выполнения.
Рекомендуемые курсы обучения:
В качестве контрольного примера рекомендуется выполнить операции задачи «Визуализация отчетности», описанные в п. 4.2. настоящего документа.
Источник
Руководство пользователя. Советы для составления
Существует множество видов предоставления справочной информации пользователю – это и FAQ (frequently asked questions, часто задаваемые вопросы) и онлайн справка и руководство пользователя (user guide) и популярные сегодня подсказки (coachmarks, см. пример ниже), обучающие видео и другие.
Существуют разные причины, по которым требуется написать руководство пользователя системы. Начиная с просьб заказчика (в моей практике был случай, когда заказчику надо было поставлять руководство пользователя после каждой итерации, чтобы с его помощью он смог бы провести приемочное тестирование функциональности итерации) и заканчивая условиями контракта, касающимися поставки готового ПО, если говорить о разработке ПО на заказ. В случае разработки собственного продукта написание руководства пользователя тоже часто имеет место.
К созданию руководства часто привлекают аналитика, если нет возможности поручить техническому писателю. В подавляющем большинстве случаев самыми полными знаниями о системе обладает именно аналитик, он же обладает умением ясно излагать свои мысли в письменной форме в силу специфики профессии. Поэтому, мне не однократно приходилось сталкиваться с созданием руководств пользователя.
Ниже я приведу несколько практик для составления хорошего руководства пользователя. Часть из них, возможно, кому-то будут полезны и при написании спецификаций требований.
1. Стандарты
Часто бывает нужно написать документ, который бы удовлетворял требованиям действующих стандартов. Это могут быть:
Если потребности проекта позволяют вам не следовать жестким стандартам, в любом случае изучение этих документов может послужить стартовой точкой для написания качественного документа.
Также может оказаться полезной книга Юрия Кагарлицкого MetaGuide. Руководство для разработчиков технической документации к программному обеспечению.
2. Структура
Хорошо продумайте структуру документа: она должна покрывать все функциональные возможности системы, быть полной и понятной.
Хорошее руководство пользователя должно содержать:
Также руководство пользователя может содержать:
Все главы и пункты, а также рисунки и таблицы лучше нумеровать, чтобы на них можно было сослаться внутри этого документа или из другого документа.
3. Пользователи
Подумайте о типичных пользователях данного ПО: необходимо, чтобы документ помогал им решать их насущные задачи.
Возможно, даже имеет смысл сделать разные разделы (или даже разные документы) для разных групп пользователей, если их взаимодействие с системой будет кардинально различаться. Например, администраторов системы (людей, отвечающих за учетные записи, права доступа и т.д.) будет интересовать совсем другая функциональность, нежели обычных пользователей.
Уважайте пользователей системы, не пишите инструкции в пренебрежительном стиле.
4. Особенности изложения
Помните, что стиль изложения в устной речи или в деловом письме отличается от оного в технической документации, и в частности, в руководстве пользователя.
Стиль руководства должен быть нейтрально-формальным – использование стилистически окрашенных слов отвлекает пользователя от сути.
Для составления хорошего документа пригодятся знания грамматики и немного психологии.
4.1 Пишите кратко и логично. Не давайте лишних деталей, не дублируйте информацию. Последовательность упоминания информации в руководстве пользователя должна совпадать с последовательностью действий пользователя:
Хорошо: In File menu, select Save item.
Хуже: Select Save item from File menu.
4.2 Используйте повелительное наклонение, не употребляйте вежливые обороты (please, could и т.д.) — излишняя вежливость именно здесь будет помехой.
Хорошо: Click Logout to log out current user account from the system.
Хуже: It is needed to click Logout to log out current user account from the system.
Хуже: If user wants to log out current user account from the system (s)he needs to click Logout.
4.3 Структурируйте информацию. Часто можно встретить совет, что надо стараться избегать списков, однако, структурированная по шагам информация всегда лучше воспринимается.
Хорошо:
To create project:
Хуже: To create project click the Create button on toolbar, on the Create Project overlay fill in all mandatory fields, click the Save button to save the project.
4.4 Не используйте будущее или прошлое время. Например, часто встречаются руководства, в которых реакция системы на действие пользователя передается фразами, сформулированными в будущем времени. У ПО нет прошлого или будущего: всё случается в настоящем как прямой результат конкретного действия пользователя. Как только событие случается, ПО реагирует.
Хорошо: When user clicks the Start button, the program starts the process.
Хуже: When user clicks the Start button, the program will start the process.
4.5 Проверяйте значение слов. Если необходимо писать документ на иностранном языке, надо стараться максимально избегать ошибок, связанных с недостаточным знанием языка.
Например, глагол «press» означает нажатие клавиши на клавиатуре, а «click» – нажатие кнопки или значка в окне программы при помощи мыши, а «hit» вообще является жаргонным словом.
Разумеется, орфографические ошибки недопустимы.
4.6 Не используйте синонимы для одного и того же термина. В IT литературе на английском (или любом другом) языке есть стандартный набор глаголов, обозначающих действия (click, double-click, select, type, press и т.д.) и такой же стандартный набор названий элементов управления. Определитесь с терминологией и придерживайтесь ее в рамках всего документа.
Например, не допускайте, чтобы в одной части документа выпадающий список назывался dropdown, а в другой точно такой же элемент – combobox или dropdown list. Это путает пользователя.
4.7 Разумно используйте сокращения и исключите жаргон.
Считается, что сокращения использовать не стоит, но если длинный термин употребляется несколько раз, то при первом упоминании в тексте надо писать полное название и рядом — аббревиатуру в скобках, а далее по тексту можно использовать только аббревиатуру. Если в документе есть глоссарий или раздел с сокращениями, они должны быть там расшифрованы.
Не используйте жаргонные слова, метафоры и термины, заимствованные из языка отличного от языка руководства.
5. Внешний вид
5.1 Продумайте стиль документа. Это может быть корпоративный шаблон или цветовая схема ПО или специально сделанный для документа дизайн.
При написании не стесняйтесь выделять важные вещи стилями или цветами (например, названия кнопок выделять жирным шрифтом). Но важно понимать, что неправильно подобранные шрифты и цвета могут затруднить восприятие содержимого документа.
5.2 Не экономьте место – разбивайте текст на короткие абзацы, используйте сравнительно крупные заголовки, начинайте новый раздел с новой страницы. Это облегчит восприятие прочитанной пользователем информации.
5.3 Используйте пиктограммы и иллюстрации. Существует мнение, что не стоит увлекаться иллюстрациями, а также включать в текст пиктограммы (icons) в руководстве пользователя. Однако графическая информация всегда лучше воспринимается и запоминается, поэтому снимки экрана и нужные пиктограммы должны присутствовать в хорошем руководстве в достаточном, но разумном количестве.
6. Поддержка
Не упускайте из виду тот факт, что ПО со временем меняется, а значит, ваш документ тоже должен меняться, чтобы оставаться актуальным.
Заключение
Примите к сведению, что раздражение от некачественного документа может быть спроецировано пользователем на ПО и, тем самым, повлиять на решение использовать продукт.
Помните главное: документ должен помогать пользователям.
Статью подготовила
Тарасюк Надежда, участник сообщества analyst.by,
Источник
Многие согласятся, что создание технической документации к продукту – не менее сложный процесс, чем написание кода к нему. Разработчики часто откладывают задачу по написанию документации пользователя в долгий ящик, поскольку считают ее трудоемкой, требующей дополнительных расходов или прямо-таки скучной.
Тем не менее, написание документации к ПО или web-сервису является важной частью жизненного цикла разработки. Если вам не нравится процесс документирования продукта, над которым вы работаете, этот обзор для вас.
В нем мы расскажем, про лучшие инструменты для создания пользовательской документации на рынке, которые превратят эту тяжелую и, казалось бы, невыполнимую задачу – в легкую прогулку.
— Но стоп, разве техническую документацию не может перекрыть техническая поддержка?
— Скорее нет, чем да. Есть внушительное число пользователей, которые с радостью обратятся к справочной документации, нежели будут писать в поддержку, ждать ответа, общаться с людьми.
Поддержка может подвести. Случайно или из-за некомпетентности сотрудников. Грубость техподдержки – тоже нередкое явление.
Также, техподдержку могут просто завалить вопросами, и она не будет успевать отвечать.
Подобные случаи негативно сказываются на репутации и лучше заранее застраховаться. Например – создать руководство пользователя.
Но написание технической документации к ПО или сервису нелегкая задача. Нужно досконально изучить программу, предсказать, с какими трудностями могут столкнуться пользователи, описать все возможности продукта, создать логичную структуру, добавить достаточно скриншотов и пояснений. И когда все будет готово – выложить документацию на сайт продукта и/или внедрить справку в ПО.
Часто подобную документацию пишут в текстовых редакторах, но это значительно усложняет и без того скучный процесс. Специализированное ПО имеет множество функций, упрощающих процесс создания руководства. Например, возможность структурировать будущую документацию, создавать разделы, делать пояснения на скриншотах, экспортировать контент в различные форматы (HTML, CHM, PDF) и многое другое.
Сегодня мы подобрали для вас 5 лучших программ и сервисов для создания пользовательской документации, которые, по нашему мнению, лучше всего подходят для своей роли.
1. Dr.Explain
Операционная система – Windows
Цена – от 10 000 рублей в год или 16000 рублей навсегда в рамках старшей версии (есть бесплатная версия)
Dr.Explain – одна из немногих программ, которая автоматизирует процесс создания документации пользователя. При написании документации перед писателем стоит задача наглядно показать, как все работает и где что находится. Для этого в руководства вставляют скриншоты с пояснениями к элементам интерфейса программы. В Dr.Explain есть специальный инструмент, который выделяет все важные элементы на скриншоте, например, кнопки или поля, и добавляет к ним аннотации (выноски) с пояснениями. Все что останется сделать писателю – снабдить их описаниями.
Второе, что бросается в глаза, когда изучаешь возможности программы — встроенные шаблоны документации. Всегда проще работать по образцу, смотреть на пример документации, дополнять и видоизменять под свой продукт. Именно это и предлагает Dr.Explain. В программе существует три шаблона документации: руководство пользователя для ПО, руководство пользователя для web-сервиса и шаблон корпоративной базы знаний.
Как бы хорошо программа не помогала писать документацию, конечная цель – это публикация контента на сайте продукта и интеграция его в продукт, чтобы пользователи могли прочитать ваше руководство. Dr.Explain позволяет экспортировать ваш проект в популярные форматы: HTML – для сайта, CHM – для встроенной в ПО справки и PDF.
Dr.Explain позволяет работать в команде через облачный сервис или локальный сервер. В программе можно задавать разделам «степень готовности». Так вы сможете контролировать процесс написания справки.
В программе имеется удобный и продуманный WYSIWYG редактор, возможность настраивать стиль вашей документации, возможность настроить контекстно-зависимую справку и что немаловажно – в ней есть русский интерфейс, так как Dr.Explain – проект отечественной команды разработчиков и продукт включен в реестр отечественного ПО.
Плюсы:
+ Большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя (аннотирование скриншотов, шаблоны документации и т.д.)
+ Русский интерфейс
+ Простая оплата для российских пользователей
Минусы:
— Отсутствие веб-интерфейса
— Отсутствие версии для Mac и Linux
— Нет вывода в ePub, markdown и другие специфические форматы
2. HelpnDoc
Операционная система – Windows
Цена – от $99 в год (есть бесплатная версия)
Главный плюс HelpnDoc – возможность экспорта в невообразимое множество форматов, тем самым возможность создания мультиформатной документации.
Создаёте документацию для мобильного приложения? Вашим пользователям нужно читать документацию с электронной книги? Нужно создать документацию к продукту на Linux, Ubutu, UNIX? Эта программа поможет.
Мощная система медиабиблиотеки. Все медиа-элементы, такие как изображения, видео, документы, фрагменты HTML-кода, управляются библиотекой: эти медиа-элементы можно использовать повторно много раз.
Нужно изменить одну картинку, а она размещена в документации десятки раз? Просто обновите элемент библиотеки, и он будет распространен на все темы, использующие его.
Благодаря редактору сценариев можно легко автоматизировать повторяющиеся задачи и сфокусировать своё внимание на сложных. Вам нужно изменить порядок тем? Заменить все элементы библиотеки? Запустите редактор сценариев, введите несколько инструкций, нажмите «Выполнить», после чего часть рутинной работы будет выполнена автоматически.
HelpnDoc анализирует написанную документацию и может показать вам неработающие ссылки, ссылки с ошибками, отсутствующие или дублирующие элементы мультимедиа. Все подобные ошибки можно увидеть в одном месте (анализаторе) и сразу же приступить к их устранению.
Плюсы:
+ Возможность создания мультиформатной документации.
+ «Сценарии» значительно упрощают и ускоряют процесс написания руководства
+ Умный анализ и проверка вашего проекта.
Минусы:
— нет русского интерфейса, и если вы будете создавать руководство на русском языке, то некоторые возможности по анализу и проверке будут недоступны.
— сравнительно сложный пользовательский интерфейс.
— сложность с оплатой лицензий для российских пользователей.
3. ClickHelp
Операционная система – любая.
Цена – от $50 в месяц.
Clickhelp в отличие от двух предыдущих – не программа, это web-сервис для создания документации.
Сервис полезен для продуктов, которые хотят выйти на международный рынок. В ClickHelp существует возможность перевода вашего руководства на любой язык, при помощи Google, конечно. Что немаловажно, изменяя исходный текст, изменения будут отображаться во всех переведенных вариантах на этих же языках.
Представьте, что пользователи открывают руководство и пытаются найти что-то по определенной теме. Вводят в поиск термин и им выдается все множество совпадений, которые только есть.
Специально для этого в ClickHelp есть ряд функций, чтобы клиенты всегда могли найти ответ на свой вопрос:
— Система полнотекстового поиска, в которой читатель можете осуществлять поиск по всему порталу документации или только по определенному набору руководств пользователя. Она обрабатывает формы слов и времена, чтобы читатели могли использовать естественный язык, учитывает близость терминов и другие факторы при ранжировании результатов.
— Система индексов. Если вы думаете, что пользователю все равно будет трудно найти какую-то информацию в вашей документации – система индексов или таксономий в ClickHelp решит эту проблему. Данная функция предназначена для того, чтобы сделать темы доступными для поиска по терминам, которые не находятся непосредственно в их содержании. Например, если в документации есть тема о SSL-шифровании, вы можете присвоить ей индексное ключевое слово «безопасность», и даже если в теме нет ни единого упоминания «безопасности» или каких-либо производных, она все равно будет доступны для поиска по этому термину.
В ClickHelp можно работать в команде. Сервис позволяет следить за процессом разработки, оставлять комментарии, от которых уведомления будут приходить на почту, раздавать роли.
Плюсы:
+ Возможность работы в команде через веб-интерфейс и отслеживание результатов.
+ Поиск по документации.
+ Автоматический перевод документации на любые языки.
Минусы:
— Достаточно сложный в освоении продукт и интерфейс только английский, что усложнит задачу понимания сервиса и его функций.
— Высокая стоимость лицензии.
— Нет возможности работать в offline-режиме.
4. HelpSmith
Операционная система – Windows
Цена – от $199.
Одной из основных возможностей HelpSmith является создание нескольких форматов справки из единого источника. Таким образом, имея один исходный текст, вы можете экспортировать его в HTML для создания веб-справки, в PDF, MS Word, а также в формат ePub для электронных книг.
Программа имеет встроенный инструмент по работе с изображениями, чем-то напоминающий Dr.Explain. В нем вы можете редактировать изображения и добавлять к ним аннотации. Кроме того, всё медиа, которое вы используете в проекте, хранится в едином репозитории, что упрощает процесс обновления и сохранения изображений в документации.
Для опытных технических писателей HelpSmith предоставляет гибкие возможности условной компиляции, позволяющие создавать разные версии одного и того же файла справки для разных аудиторий пользователей.
Следует отметить, что файл справки или систему веб-справки можно легко интегрировать в ваше приложение или веб-сайт, поэтому вы можете предоставлять контекстно-зависимую справку, экспортируя список тем в файл заголовка, совместимый с вашей IDE, такой как C #, VB .NET, Delphi, C++, MS Office VBA.
Также, из необычных дополнительных функций HelpSmith является — «Подсветка синтаксиса» — для создания документации API, файлов справки с примерами кода и любых других видов документации, содержащей программный код, написанный на различных языках программирования.
Плюсы:
+ большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя
+ простота и удобства использования.
Минусы:
— Отсутствие простого механизма многопользовательской работы
— Интерфейс и материалы на английском языке
— Отсутствие Mac и веб-версии
5. MarkdownPad
Операционная система – Windows
Цена – бесплатно. Есть платная версия – $15.
MarkdownPad — известный редактор Markdown для Windows. Он прост и так же удобен в использовании, как Microsoft Word, и поставляется с редактором WYSIWYG, поэтому вам даже не нужно знать Markdown.
MarkdownPad отлично подходит, если вам нужно быстро выложить документацию на сайт, создать веб-сайт и все, что связано с HTML. Вы можете в любой момент посмотреть, как будет выглядеть ваша документация, используя предварительный просмотр.
Все настраивается под себя. Вы можете воспользоваться широкими возможностями настройки, такими как макеты, шрифты и размеры. Вы также можете включить свои собственные таблицы стилей CSS. Он поставляется со встроенным в платформу редактором CSS, поэтому вы можете стилизовать текст по своему вкусу.
Плюсы:
+ Очень удобная и в целом простая программа, что даже не получилось написать про неё больше 3 абзацев
+ Стоимость.
Минусы:
— Малый функционал, по сравнению с большинством подобных инструментов.
Заключение
Пользовательская документация – незаменимый инструмент, позволяющий укреплять лояльность пользователей, прикрывать техподдержку, повышать SEO-факторы продукта. Кроме того, наличие технической документации — один из основных критериев допуска в Реестр отечественного ПО Минцифра России.
Создание действительно качественной документации, которая будет приносить пользу – тяжелая задача, на которую придется потратить немало времени и сил. Специально для упрощения этой задачи и были созданы подобные HAT (Help Authoring Tool) программы, а мы постарались предоставить вам список лучших таких инструментов.
Руководство пользователя – это основной документ в составе эксплуатационной документации на автоматизированную систему (ГОСТ 34). Очевидно ли это?
Назначение руководства пользователя
Цель создания документа заключается в том, чтобы предоставить пользователю возможность самостоятельно решать свои прикладные задачи с помощью системы. Этой цели может служить и введение в предметную область, и ознакомление со всеми возможностями программы, и описание конкретных процедур решения задач, и приведение различных инструкций. Иногда Руководство пользователя больше похоже на справочник, к которому можно обращаться в процессе работы, а иногда – на учебник, который позволяет изучить принципы работы с программой и ее возможности, а затем применять их на практике.
Состав типового руководства пользователя
Конкретный подход к написанию определяется многими факторами:
– назначением программы и областью ее применения;
– сложностью программы;
– количеством разнообразных вариантов использования.
Принимая во внимание все различия и особенности, сложно привести структуру любого Руководства пользователя к одному виду. Тем не менее, РД 50-34.698 предлагает нам такой список разделов:
– Введение, где указывают область применения ПО, краткое описывают его возможности, требуемый уровень знаний пользователя и список документов, которые необходимо изучить помимо настоящего руководства;
– Назначение и условия применения, где описывают виды деятельности и функции, которые автоматизированы и условия, при соблюдении которых автоматизация используется;
– Подготовка к работе, где описывают комплектность дистрибутива, порядок установки и загрузки программы, а также способ проверки ее работоспособности;
– Описание операций, представляет собой основной раздел, где описывают функции программы, процессы работы с данными, выполнение конкретных задач пользователя;
– Аварийные ситуации, где описывают действия в нештатных ситуациях – сбоях в программе, ошибок в данных и т.д.;
– Рекомендации по освоению, где приводят методические рекомендации по изучению программы и примеры использования.
Данная структура может меняться и дополняться – например, основной раздел часто разбивают на несколько значимых разделов по группам функций или задач, также в современных системах нередко добавляют раздел Интерфейс пользователя, где описывают взаимодействие пользователя с программой с примерами и снимками экрана.
Стандарты для руководства пользователя
Наличие Руководства пользователя регламентируется ГОСТ 34.201, а структура и содержание – РД 50-34.698. Однако, в зависимости от сложности, назначения и области применения ПО, различные Руководства пользователя могут отличаться друг от друга по способу, методике и стилю изложения.
Стоимость разработки руководства пользователя
|
Наименование документа |
Наименование стандарта |
Стоимость разработки |
|---|---|---|
|
РП на автоматизированную систему |
РД 50-34.698 |
70 тыс. р. |
Грамотно написанное Руководство пользователя может сэкономить значительное количество времени на обучение и адаптацию пользователя к программе, а также снизить количество ошибок в работе что, в свою очередь, повышает экономическую эффективность системы. Если вы не хотите вникать во все тонкости создания Руководства пользователя, но хотите иметь полный, качественный и полезный документ – обратитесь в компанию ТехРайтКонсалт, и мы применим весь наш опыт и знания для решения вашей задачи по доступной цене!
Возможно, вас также заинтересует:
– разработка руководства администратора;
– создание руководства программиста;
– разработка руководства оператора.
Руководства по пользованию программами
Рекомендации
- Новинки
- Рекомендации
только полные версии книг
полная версия
Веденеева Елена Анатольевна
Книга посвящена вычислительным возможностям Microsoft Excel последней версии, в ней рассмотрены все встроенные функции и формулы, объясняется принцип создания и применения каждой функции, приводятся…
Подробнее
Байков Дмитрий ВладимировичВладимир Байков
Перефразируя известную пушкинскую строку, можно сказать, что в наше время ПК все возрасты покорны. За компьютером или ноутбуком, подключенными к Интернету, можно увидеть и розовощекого внука, и…
Подробнее
Волков Владимир Борисович
Microsoft Excel – одна из самых загадочных и интересных программ в пакете MS Office 2010. Интересна она многочисленными средствами автоматизации работы, оформления документов и богатыми…
Подробнее
Ташков Петр
В книге изложены методы восстановления данных с различных носителей информации – жестких дисков, массивов RAID, CD, DVD, карт флэш-памяти, карт фотоаппаратов и мобильных телефонов. Ремонт…
Подробнее
Вадзинский Ратмир Николаевич
В книге рассмотрены встроенные средства статистического анализа табличного процессора Excel. Большинство глав начинается с краткого изложения основных понятий теоретической и прикладной статистики,…
Подробнее
Краинский И
В данной книге доступно и полно описан Microsoft Word 2007 – самый современный и удобный текстовый редактор.
Отличительной особенностью самоучителя является то, что выполнение большинства операций…
Подробнее
Поршнев Сергей ВладимировичБеленкова Ирина Вячеславовна
В пособии изложены необходимые начальные сведения о терминологии и методах вычислительной математики. Рассмотрены уравнения и системы уравнений, задачи интерполяции и аппроксимации, численное…
Подробнее
Шутенко Юрий Тихонович
Книга посвящена расширению возможностей приложений Visual FoxPro за счет использования современных технологий. Показано применение различных Web-технологий, таких как ASP.NET, LINQ, Silverlight,…
Подробнее
Ватаманюк Александр Иванович
Вы купили компьютер и сразу же столкнулись с массой непредвиденных проблем? Ваша машина «тормозит», «вешается»? Регулярно возникают мелкие неполадки? Тогда эта книга – для вас! С ее помощью вы легко…
Подробнее
Мединов Олег
Эта книга поможет вам разобраться в премудростях Microsoft Excel 2007. Информационная насыщенность учебного материала позволяет утверждать, что мультимедийный курс будет интересен и новичкам, и…
Подробнее
Пастернак Евгения Борисовна
Разве книга о таких непонятных компьютерах не должна быть страшно сложной и дико скучной? Разве она может быть смешной, интересной, очень простой, да еще и красиво оформленной? Конечно! Ведь это – не…
Подробнее
Петелин Юрий ВладимировичРоман Петелин
Описана работа с новейшей версией профессиональной виртуальной звуковой студии Steinberg Cubase 7.5. Детально рассмотрены интерфейс и приемы эффективной работы с программой, методики редактирования…
Подробнее
Пастернак Евгения Борисовна
Согласно современным правилам хорошего тона любая леди должна знать, что такое компьютер в принципе и Microsoft Office в частности. Автор этой книги, Евгения Пастернак, поможет вам освоить самые…
Подробнее
Бэнкер Кайл
MongoDB – это документо-ориентированная база данных, предназначенная для гибкой, масштабируемой и очень быстрой работы даже при больших объемах данных. При ее проектировании изначально закладывалась…
Подробнее
Жвалевский Андрей Валентинович
Веселый и интересный самоучитель работы на компьютере, оснащенном новейшей операционной системой Windows Vista. В ходе непринужденной беседы с читателем автор научит «укрощать» программы, настраивать…
Подробнее
Смирнов Юрий Константинович
Раскрыто множество секретов восстановления винчестеров SATA и IDE с дефектами магнитного слоя и логическими нарушениями в структуре разделов. Показано, как своевременно обнаруживать появление…
Подробнее
Бойцев Олег Михайлович
Подумайте, сколько ценной информации хранится на вашем компьютере – начиная с достаточно безобидных сведений о вас и вашей работе и заканчивая действительно конфиденциальными данными (пароли к…
Подробнее
Зозуля Юрий Николаевич
Если вы только приступили к освоению азов компьютерных технологий, если вы пока еще задумываетесь, прежде чем нажать какую-либо клавишу на клавиатуре, если вы поминутно опасаетесь забыть, как…
Подробнее
Питоньяк Эндрю
Эта книга – первое выходящее на русском языке издание по программированию в OpenOffice.org, в основе которого лежит статья Эндрю Питоньяка «Макросы». Эндрю Питоньяк признанный мастер по написанию…
Подробнее