Предыдущий «Метод Squiap Squiap: Руководство пользователя API-MEDOOO» представила метод суммирования MEDOO, но также представила широко используемую обычную API, затем ввести 2 расширенных API: API запроса и API и цитата. Здесь вы начнете объяснять использование API запроса.
Способ запроса: API запроса, вставьте новую запись в листе передачи данных.
query($query)
// Запрос [строка]: оператор SQL QueryВозвращаемое значение: [Объект]: Объект объявления PDO.
Совет: Этот метод используется для настройки или сложных запросов SQL. Каждое данные должны быть вставлены, используйте метод цитаты для предотвращения инъекций SQL.
$database = new medoo();
$database->query("CREATE TABLE table (
c1 INT STORAGE DISK,
c2 INT STORAGE MEMORY
) ENGINE NDB;");
$data = $database->query("SELECT email FROM account")->fetchAll();
print_r($data);Способ запроса позволяет гибко заказывать любой из сложных запросов SQL, который мы хотим использовать, но также обращать внимание на вопросы безопасности в инъекции SQL. Чтобы предотвратить инъекцию SQL, мы должны использовать метод цитаты, который должен быть введен в следующую статью.
Версия Medoo: 0.9.5
Оригинальное название:Способ запроса: Руководство пользователя запроса API-MEDOOO
Оригинальная ссылка:http://loiy.net/post/660.html
Перепечатано на: https://my.oschina.net/veekit/blog/272564
7.3. Формирование запросов
В данном разделе подробно рассмотрены правила формирования общих и строчных запросов на примере запроса к текущему БД. Отличительные особенности формирования глобальных запросов описаны в разделе 7.4..
7.3.1. Общие понятия
Процесс формирования запроса включает в себя задание условий поиска, а также указание перечня разделов БД, в которых следует искать документы.
Сформированный запрос запускается на выполнение, ход которого отображается на экране. В процессе выполнения можно остановить запрос, не дожидаясь его самостоятельного завершения.
После завершения выполнения запроса к текущему БД автоматически открывается Окно выборки для работы с отобранными документами. При этом как непосредственно из Окна выборки, так и из окна исходного запроса предусмотрена возможность уточнения запроса для дополнительного отбора документов из числа включенных в выборку.
При поиске документов в текущем Банке Документов можно работать с несколькими запросами и выборками документов одновременно.
7.3.2. Формирование общих запросов.
Окно запроса
Формирование общего запроса производится в специальном Окне запроса, примерный вид которого приведен на рис. 7.1.
Рисунок 7.1. Окно формирования общего локального запроса.
В левой части Окна формирования запроса расположена Панель структуры, содержащая иерархический список областей поиска текущего БД. В этом списке пользователем отмечаются те разделы БД, в которых должен производиться поиск документов согласно заданным условиям. При необходимости можно выбрать сразу все области поиска (для этого достаточно отметить корневой элемент списка — «Области поиска»).
В правой части расположена таблица для задания условий по каждому атрибуту. Задание условий осуществляется в соответствии с правилами Языка запросов CROS (см.
раздел 7.2.).
В верхней части расположена настраиваемая инструментальная панель.
В нижней части – строка состояния, в которой отображается ход выполнения запроса и информация об его результатах.
Панель инструментов Окна формирования общего запроса
При открытии окна общего запроса в Главное меню программы добавляется пункт «Запрос». Команды, включенные в этот пункт, предназначены для создания и изменения запроса, запуска его на выполнение, просмотра результатов запроса и выполнения других действий.
Кнопки, соответствующие командам пункта Главного меню «Запрос», вынесены на панель инструментов, располагающуюся в верхней части Окна формирования запроса.
Описание команд пункта Главного меню «Запрос» и соответствующих им кнопок панели инструментов приведено в таблице.
| Команда пункта меню «Запрос» | Кнопка панели инструментов | Комбинация клавиш | Описание |
| Поиск |  |
+ | Запускает поиск документов по заданным критериям отбора |
| Прервать запрос |  |
— | Останавливает поиск документов, не дожидаясь его завершения.
Команда доступна только в процессе выполнения поиска. |
| Просмотр результатов |  |
+ | Отображает информацию о результатах поиска, открывая окно выборки документов (см. раздел 8.1.).
Команда доступна по завершении выполнения запроса (если отобран хотя бы один документ). |
| — |  |
— | Выводит информацию о результатах поиска (количестве найденных документов). Команда доступна по завершении выполнения запроса. |
| Подсчет вхождений |  |
— | Включает/выключает режим подсчета количества найденных фрагментов, удовлетворяющих условиям поиска, в документ. |
| Уточнить запрос |  |
+ + | Позволяет уточнить запрос, выполнив поиск документов среди документов текущей выборки. Для каждого уточнения открывается новое Окно запроса (см. раздел 7.3.2.). |
| Удалить |  |
Удаляет текущее условие (или группу помеченных условий) из списка условий запроса. |
Задание условий общего запроса
Список условий поиска для общего запроса расположен в правой части Окна формирования запроса (см. рис. 7.1.). Он представлен в виде таблицы, каждая строка которой соответствует одному условию запроса и формируется из следующих элементов:
- логической связки с предыдущим условием (для первого условия в запросе логическая связка не указывается);
- атрибута, по которому производится сравнение;
- вида сравнения;
- поискового значения.
Крайний левый столбец таблицы позволяет отметить необходимые условия запроса. Пометка условий выполняется щелчком левой клавиши мыши или нажатием клавиши <Пробел>.
Последняя, пустая строка таблицы предназначена для ввода нового условия и отображается даже в том случае, если ни одного условия поиска не задано.
Формирование условий осуществляется в соответствии с правилами Языка запросов CROS (см.
раздел 7.2.).
Для добавления нового или редактирования существующего условия необходимо нажать клавишу <Enter> (или выполнить двойной щелчок мышью) на соответствующей строке таблицы, поочередно выбрать из предлагаемых списков логическую связку, атрибут и вид сравнения 16, после чего в графе «Условие» ввести поисковое значение.
Примечание: Если используются виды сравнения «Внутри интервала» или «Вне интервала», в графе «Условие» отображаются два элемента редактирования, первый из которых предназначен для ввода начального, а второй – конечного значения интервала. При выборе вида сравнения «В интервале слов» первый элемент редактирования служит для ввода поискового значения-контекста, а второй – для задания длины интервала.
Лишние условия можно удалить с помощью клавиши <Delete> (или кнопки на панели инструментов Окна формирования запроса), предварительно пометив их в крайнем левом столбце таблицы.
7.3.3. Формирование строчных запросов
Окно формирования строчного запроса
Формирование строчного запроса производится в специальном Окне запроса, примерный вид которого приведен на рис. 7.2.
Рисунок 7.2. Окно формирования строчного локального запроса.
Окно формирования строчного запроса по своему внешнему виду схоже с Окном формирования общего запроса. Отличие заключается в размещении в правой части Окна строчного запроса двух элементов: текстового поля для задания условий поиска в тексте документа (поля ввода строчного запроса) и списка сохраненных запросов. Кроме того, панель инструментов имеет расширенный, по сравнению с панелью инструментов общего запроса, набор кнопок (см. ниже).
Панель инструментов Окна формирования строчного запроса
При открытии Окна формирования строчного запроса в Главное меню программы добавляются пункты «Запрос» и «Список». Команды, включенные в эти пункты, предназначены для создания и изменения запроса, запуска его на выполнение, просмотра результатов запроса и выполнения других действий.
Кнопки, соответствующие командам пунктов Главного меню «Запрос» и «Список», вынесены на панель инструментов, располагающуюся в верхней части Окна формирования запроса.
Описание команд пункта Главного меню «Запрос» и соответствующих им кнопок панели инструментов приведено в таблице.
| Команда пункта меню «Запрос» | Кнопка панели инструментов | Комбинация клавиш | Описание |
| Поиск | |
+ | Запускает поиск документов по заданным критериям отбора |
| Прервать запрос | |
Останавливает поиск документов, не дожидаясь его завершения.
Команда доступна только в процессе выполнения поиска. |
|
| Просмотр результатов | |
+ | Отображает информацию о результатах поиска, открывая окно выборки документов (см. раздел 8.1.).
Команда доступна по завершении выполнения запроса (если отобран хотя бы один документ). |
| Подсчет вхождений | |
Включает/выключает режим подсчета количества найденных фрагментов, удовлетворяющих условиям поиска, в документ. | |
| Уточнить запрос | |
+ + | Позволяет уточнить запрос, выполнив поиск документов среди документов текущей выборки. Для каждого уточнения открывается новое Окно запроса (см. раздел 7.3.). |
| Поиск | |
+ | Запускает поиск документов по заданным критериям отбора |
| Прервать запрос | |
Останавливает поиск документов, не дожидаясь его завершения.
Команда доступна только в процессе выполнения поиска. |
|
| Морфологический анализ |  |
— | Включает/выключает режим морфологического анализа (см. раздел 7.3.3.) |
| Подсчет вхождений | |
— | Включает/выключает режим подсчета количества найденных фрагментов, удовлетворяющих условиям поиска, в документ. Отключение режима подсчета найденных вхождений может увеличить скорость обработки запроса. |
| Сохранить текст в файле |  |
+ |
Сохраняет строчный запрос в указанном пользователем текстовом файле на диске. |
| Загрузить |  |
+ | Загружает текст строчного запроса из указанного пользователем файла на диске. |
| Распечатать |  |
+ | Выводит текст строчного запроса на устройство печати. |
| Отмена изменения запроса |  |
+ | Отменяет последнее изменение строчного запроса |
| Логическое условие ИЛИ |  |
+<8> | Вставляет в текст строчного запроса (в позицию курсора) логическое выражение «ИЛИ» (включая необходимые пробелы) |
| Логическое условие И |  |
+<7> | Вставляет в текст строчного запроса (в позицию курсора) логическое выражение «И» (включая необходимые пробелы) |
| Логическое условие НЕ |  |
+<6> | Вставляет в текст строчного запроса (в позицию курсора) логическое выражение «НЕ» (включая необходимые пробелы). |
| Скобки |  |
+<9> | Вставляет в текст строчного запроса (в позицию курсора) открывающую и закрывающую скобки. |
| Вырезать |  |
+ | Перемещает выделенный фрагмент текста строчного запроса в буфер обмена. |
| Копировать |  |
+ | Копирует выделенный фрагмент текста строчного запроса в буфер обмена. |
| Вставить |  |
+ | Вставляет текст из буфера обмена в текст строчного запроса (в текущую позицию курсора). |
| Удалить | |
Удаляет выделенный фрагмент в поле формирования строчного запроса. | |
| Выделить все | — | + | Выделяет весь текст строчного запроса. |
| Найти в запросе |  |
++ | Ищет в тексте строчного запроса указанное пользователем выражение. |
| Замена в запросе |  |
+ | Находит и заменяет в тексте строчного запроса одно выражение на другое. |
| Перенос по словам |  |
+ | Включает/выключает режим переноса текста в поле ввода строчного запроса. |
| Шрифт |  |
— | Позволяет выбрать шрифт для отображения текста строчного запроса. |
| Проверить подстановку | — | ++ | Позволяет просмотреть результат подстановки понятий словаря в текст строчного запроса до его выполнения (см. раздел 7.3.3.). |
В следующей таблице приведен перечень команд, включенных в пункт Главного меню «Список» и используемых для работы со списком ранее выполненных запросов.
| Команда пункта меню «Список» | Кнопка панели инструментов | Комбинация клавиш | Описание |
| Вставить в запрос |  |
Вставляет выражение сохраненного запроса, выделенного в списке (или группы отмеченных запросов), в поле ввода строчного запроса (в текущую позицию курсора). | |
| Добавить в запрос |  |
+ | Добавляет выражение сохраненного запроса, выделенного в списке (или группы отмеченных запросов), в поле ввода строчного запроса (в конец введенного выражения). |
| Заменить запрос |  |
Заменяет выражение в поле ввода строчного запроса на сохраненный запрос, выделенный в списке (или группу отмеченных запросов) | |
| Заменить и выполнить запрос |  |
+ | Заменяет выражение в поле ввода строчного запроса на сохраненный запрос, выделенный в списке (или группу отмеченных запросов), и запускает его на выполнение. |
| Удалить |  |
Удаляет сохраненный запрос, выделенный в списке (или группу отмеченных запросов). | |
| Шрифт таблицы | — | ++ | Позволяет выбрать шрифт для отображения списка сохраненных запросов. |
| Шрифт заголовка | — | ++ | Позволяет выбрать шрифт для отображения заголовка списка сохраненных запросов. |
| Сохранить в файле | — | ++ | Позволяет сохранить в текстовом файле список ранее выполненных строчных запросов.
Для каждого запроса в файл выводятся следующие значения (разделенные символом «|»): текст запроса, дата и время его выполнения, а также количество найденных документов. |
Задание условий общего запроса
Условия строчного запроса задаются в виде логического выражения, включающего набор поисковых значений, объединенных с помощью логических операторов «И», «ИЛИ», «НЕ» и скобок.
Логическое выражение вводится в текстовом поле в правой верхней части Окна запроса. Формирование выражения осуществляется в соответствии с правилами Языка запросов CROS (см.
раздел 7.2.).
В правой нижней части окна содержится список выражений ранее выполненных строчных запросов (с указанием даты создания запроса). При необходимости, нажав клавишу > (либо выполнив двойной щелчок мышью или нажав кнопку инструментальной панели – см. выше) на соответствующей строке списка, можно перенести созданное ранее выражение в поле ввода запроса, после чего откорректировать его или сразу запустить на выполнение.
Максимальное количество хранящихся программой строчных запросов задается в окне «Настройка параметров» (см.
раздел 10.5.). При задании значения «0» запросы не запоминаются. Лишние запросы можно удалить из списка с помощью клавиши <Delete> (или кнопки на панели инструментов Окна формирования запроса), предварительно пометив их в крайнем левом поле.
Нажав кнопку 
панели строчного запроса (или выбрав пункт меню Запрос Морфологический анализ), можно задействовать режим Морфологического анализа (см. ниже).
Для включения в текст строчного запроса тематически объединенных групп слов удобно использовать Словарь подстановок. При этом вместо группы поисковых значений в запросе указывается код словаря (в формате %КОД%), который при выполнении поиска заменяется системой на соответствующую группу слов из Словаря подстановок, объединенных оператором «ИЛИ».
Результат подстановки можно просмотреть до выполнения запроса. Для этого требуется выбрать пункт Главного меню Запрос Проверить подстановку (клавиши <Ctrl>+<Alt>+<Ins>).
Помимо рассмотренной возможности, система позволяет пользователю самостоятельно выбрать из словаря и включить в текст формируемого запроса необходимые подстановочные значения. Для выбора подстановки следует выполнить пункт меню Режимы Словарь подстановок, в открывшемся окне словаря отметить требуемые значения и нажать кнопку «Выбрать».
Подробнее о создании и использовании Словаря подстановок см. ниже.
Морфологический анализ
Морфологический анализ – это режим поиска, при котором наряду с исходным словом отыскиваются все его возможные словоформы в предложениях: все падежи единственного и множественного числа для существительных, прилагательных и причастий, а также все формы и времена для глаголов.
Для корректного отыскания всех возможных словоформ все существительные, прилагательные и причастия должны задаваться в именительном падеже единственного числа, а глаголы – в неопределенной форме.
При использовании служебных символов шаблона («?» или «*»), режим Морфологического анализа активизируется в том случае, если они стоят в начале или середине слова.
Режим Морфологического анализа доступен только в строчном запросе и задействуется при нажатии кнопки 
на панели строчного запроса (или выборе пункта меню Запрос Морфологический анализ) и активизируется для всех слов в поисковом значении, заканчивающихся на букву русского алфавита. Слова, заканчивающиеся на букву латинского алфавита, ищутся только в исходной форме.
Словарь подстановок
Словарь подстановок может быть сформирован в любом банке документов системы CROS. Он предназначен для создания, сохранения и последующего использования в строчных запросах групп поисковых значений. Применение словаря подстановок позволяет существенно упростить создание запросов, в которые требуется включать множество поисковых значений единой тематики.
Каждой группе поисковых значений, хранимой в Словаре подстановок, сопоставлено уникальное текстовое значение – имя группы. Имя группы называют также кодом словаря, а сами поисковые значения – понятиями словаря. Каждая группа понятий словаря с сопоставленным ей кодом образуют одну запись словаря.
Работа со Словарем подстановок осуществляется в диалоговом окне «Словарь» (см. рис. 7.3.), для вызова которого следует выбрать пункт Главного меню Режимы Словарь подстановок. 
Рисунок 7.3. Диалоговое окно «Словарь»
Основную часть окна диалога занимает список всех групп поисковых значений, хранимых в Словаре подстановок. В каждой строке списка выводится код словаря (т.е. имя группы) и перечень соответствующих этому коду понятий, разделенных точкой с запятой. Крайняя левая графа списка служит для пометки записей словаря.
В верхней части окна расположена инструментальная панель. С ее помощью можно просматривать и изменять содержимое словаря, а также выполнять поиск записей. Ниже приведено описание кнопок панели инструментов и соответствующих им комбинаций клавиш.
| Кнопка | Комбинация клавиш | Выполняемое действие |
 |
+<2> | Показать все записи словаря. Отображает полный список записей словаря, вне зависимости от состояния кнопок  и  . |
|
+<3> | Показать найденные записи. Если кнопка нажата, в окне отображаются только записи, найденные в результате последнего поиска. |
|
+<4> | Показать помеченные записи. Если кнопка нажата, в окне отображаются только ранее помеченные записи словаря. |
 |
Добавить запись. После нажатия этой кнопки на экран выводится окно «Добавление записи», предназначенное для создания в словаре новой группы поисковых значений. | |
 |
+ | Изменить запись. После нажатия этой кнопки на экран выводится окно, предназначенное для коррекции текущей (выделенной) записи словаря (см. ниже, рис. 7.4.). |
 |
Удалить запись. После нажатия этой кнопки система предложит удалить выделенное/помеченные понятия словаря. |
В нижней части окна расположено поле поиска, предназначенное для поиска записей словаря по любому фрагменту кода или понятия. Для выполнения поиска в этом поле необходимо ввести искомое значение и нажать кнопку 
(или комбинацию клавиш <Ctrl>+<F>). Курсор в поле поиска перемещать не требуется, после начала ввода фокус на него будет переведен автоматически. При задании условия поиска могут использоваться шаблоны «?» и «*», логические связки «И», «ИЛИ», «НЕ», а также скобки. Если поиск завершился успешно, система перейдет в режим просмотра найденных записей (кнопка нажата).
Добавление новых или коррекция уже имеющихся записей словаря осуществляется в окнах диалога «Добавление записи» и «Изменение записи» (внешний вид этих окон идентичен, см. рис. 7.4.), для вызова которых предназначены соответственно кнопки и на панели инструментов окна «Словарь».
.
Рисунок 7.4. Окно диалога «Изменение записи»
В верхней части окна расположено поле для ввода кода словаря (имени группы), под ним – список соответствующих данному коду понятий (группа поисковых значений). Последняя, пустая строка списка предназначена для ввода нового понятия.
Чтобы добавить или изменить какое-либо понятие, следует выделить соответствующую строку списка и нажать клавишу <Enter> (или выполнить двойной щелчок мышью), после чего ввести новое или откорректировать имеющееся значение.
Ввод/коррекция значения может осуществляться как непосредственно в активном элементе списка, так и с помощью встроенного в систему текстового редактора. Для вызова редактора предназначена кнопка 
, отображаемая в правой части редактируемого элемента списка (можно использовать также комбинацию клавиш <Ctrl>+<F2>).
Порядок следования понятий в списке можно изменить, используя кнопки «Вверх» и «Вниз».
Для удаления понятия необходимо выделить его в списке и нажать кнопку «Удалить». Если требуется удалить несколько понятий, их следует предварительно отметить, щелкнув мышью в крайнем левом поле.
Работа с окном «Словарь» возможна в двух режимах:
- в режиме формирования строчного запроса;
- в режиме редактирования (изменения, добавления и удаления записей).
В первом случае вызов диалогового окна «Словарь» производится при активном окне строчного запроса. При этом можно использовать словарь не только для формирования строчного запроса, но и осуществлять редактирование записей словаря.
В рассматриваемом режиме двойной щелчок мышью (а также нажатие клавиши <Enter> или кнопки «Выполнить») на любой записи Словаря помещает соответствующую подстановку в окно запроса. Если при открытии окна «Словарь» в окне запроса было выделено поисковое значение (для поиска фрагмента следует использовать символы шаблона «*» и «?»), среди подстановок автоматически будет найдено и выделено соответствующее значение. Изменение, добавление и удаление записей словаря производится с помощью соответствующих кнопок на инструментальной панели диалогового окна (см. выше).
Если в системе закрыты все диалоговые окна, вызов окна «Словарь» производится в режиме редактирования. В этом режиме двойной щелчок мышью (а также нажатие клавиши <Enter> или кнопки «Выполнить») на выделенной записи Словаря приводит к открытию окна диалога «Изменение записи словаря подстановок» для редактирования данной записи. Также как и в режиме формирования запроса, для изменения, добавления и удаления записей могут быть использованы кнопки инструментальной панели диалогового окна «Словарь».
7.3.4. Выполнение запроса и просмотр результатов.
Сформированный запрос запускается на выполнение кнопкой на панели инструментов Окна формирования запроса.
При необходимости можно прервать выполнение запроса, нажав на панели инструментов кнопку .
Ход выполнения поиска отображается в строке состояния в нижней части окна запроса. По окончании локального поиска формируется выборка документов, для работы с которой открывается Окно выборки (см.
раздел 8.1.).
Результатом пустого запроса, в котором не задано никаких условий, является совокупность всех документов отмеченных областей поиска или всего БД, если отмечены все области поиска. Поэтому для работы со списком документов отдельных областей поиска или всего БД следует создать новый запрос и, не вводя никаких условий, запустить его на выполнение.
7.3.5. Уточнение запросов
После выполнения каждого запроса предусмотрена возможность его уточнения. Уточнение может быть многократным, количество последовательных уточнений не ограничено.
В ходе каждого уточнения открывается новое Окно запроса (соответственно, строчного или общего), в котором пользователем создается новый запрос. При запуске его на выполнение, поиск документов осуществляется среди документов предыдущей выборки.
Переход к уточнению запроса осуществляется при нажатии кнопки 
в верхней панели Окна выборки или Окна запроса, а также при выборе пункта меню Режимы, Уточнить запрос.
Окна исходных выборок и запросов при уточнении не закрываются, активизация каждого окна может осуществляться с помощью пункта меню Окна.
Вместе с тем, при уточнении запроса из окна исходного запроса в настройках системы (пункт меню Режимы Настройка) может быть предусмотрена возможность автоматического закрытия окна исходного запроса (см.
раздел 10.5.).
Писать руководство пользователя по шаблону. Удобно? Удобно
Время на прочтение
4 мин
Количество просмотров 5.1K
Команда, разрабатывающая софт для создания пользовательской документации, делится лайфхаками на тему написания идеальной пользовательской документации для тех, кто далёк от написания руководств к программе.
Для чего мы сами конструируем некоммерческие образцы документации и инструкций для пользователей
Наш проект существует и развивается уже долгое время, практически шестнадцать лет, если быть точнее. За этот срок была сформирована определенная база, где собраны самые актуальные и насущные вопросы, которые возникают перед людьми, создающими справочные элементы к своему проекту.
Ведя диалог с нашими клиентами, мы смогли выделить их потребности и понять основную «боль». Если обобщить, основная проблема заключалась в том, что ни одна программа для создания файл-справок и инструкций не могла выполнить самую нудную, энергозатратную часть проекта — само разрабатывание и оформление этой пользовательской документации
Даже имея осознание того, что файл-справка — неотъемлемый и действительно полезный элемент для пользователя, очень редко возникает мотивация оформить его грамотно и качественно. Еще реже желание возникает, когда в написании пользовательской документации нет опыта или специалистов, которые бы этот опыт имели. Обычно, эта обязанность с легкой руки падает на плечи самих создателей программы, людей, занимающихся тестированием, аналитикой, специалистам поддержки или даже руководителей компании, которые тоже не совсем понимают, как грамотно создать что-то подобное.
Отсюда вытекает еще одна загвоздка. Люди, у которых нет опыта и в принципе понимания, как начать и что туда вносить, просто не знают, как создать качественное руководство для пользователей. В таких случаях большинство следует привычному пути: загуглить определение и найти готовый шаблон.
И с какой-то стороны, это разумно. Мы достаточно часто сталкиваемся с такими запросами, пользователи просят у нас пошаговое руководство или хотя бы костяк готовой инструкции.
Так вышло, что потребности наших клиентов практически на сто процентов входят в нашу экспертную сферу. И мы приняли решение по возможности помочь всем, кто хочет (или вынужден) заниматься созданием файл-справок и инструкций к своему продукту и предоставить возможность получить образцы, которые могут послужить базой и легко быть адаптированными под конкретный запрос.
В связи с этим, мы сами создали готовые образцы и костяки шаблонных проектов в программе. Что входит в нашу базу:
-
Руководство пользователя программного обеспечения.
-
Руководство пользователя web-сервиса.
-
Корпоративная база знаний компании.
В чем удобство создания руководства пользователя по образцу
Вы бережете своё время.
Адаптируя уже созданный образец под свой продукт, вы не тратите время на создание основы с нуля, вам не нужно тратить время, чтобы найти мастер-класс о том, как правильно это сделать. Используя готовый шаблон документации, вы значительно экономите время на создание структуры проекта с нуля и на поиск и изучение информации о том, как это делается.
Вы сосредотачиваете внимание на вашей программе, а не на создании файл-справки
В шаблоне уже есть текстовые и графические вставки, вы можете сами добавлять нужный контент в предложенные места и не продумывать вариант оформления.
Наглядность.
Все образцы и костяки инструкций для пользователя изначально настроенные с динамическими стилями оформления, которые помогут вам быстрее освоиться и разобраться, как можно использовать это для быстрого выполнения своей цели.
Адаптация шаблонов и образцов под ваш проект.
Всё, что находится в шаблонах, можно назвать нашим советом, который был создан на основе многолетнего опыта в данной сфере и выработанной экспертностью. Абсолютно всё в этих шаблонах может быть подвержено адаптации, так как для пользовательской документации нет жестких стандартов, она должна быть выстроена персонально под ваш продукт.
О шаблонах
За 15 лет мы смогли подвергнуть аналитике более сотни разных файл-справок, инструкций и технических документаций, что дало нам возможность сделать вывод и определить шаблонные разделы, которые могут быть применены к огромному количеству программ, после чего мы интегрировали их в наши образцы. Давайте немного подробнее поговорим о структуре.
Обзор возможностей программ. Здесь идет краткое содержание сути вашего продукта. Где вы рассказываете о том, для чего нужна ваша программа. Какие боли и потребности она удовлетворяет, на что способна.
Пользовательский интерфейс. Здесь вы можете наглядно показать вашему клиенту интерфейс, ознакомить его со всеми режимами, дополнительными кнопками и.т.д. Если пользователь может персонализировать интерфейс под себя, об этом тоже лучше указать именно в этом разделе.
Типовые задачи. Здесь нужно максимально подробно познакомить пользователя со всеми основными возможностями программы и детально описать ряд задач и вопросов, которые клиент сможет решить с её помощью. В нашем образце этот блок сформирован из двух подразделов. В подразделе «Примеры использования» лучше всего рассказать пользователю, как ваш продукт будет решать его вопросы и задачи. Если обобщить, то в этом подразделе вы рассказываете про клишированные проблемы, с которыми сталкивается большинство пользователей. В подразделе «Лучшие практики» лучше разместить максимально полезную информацию о том, как упростить свою работу в программе и как пользоваться ей максимально эффективно.
Особые случаи. Здесь нужно рассказать пользователю про то, какие трудности могут возникнуть и как их решить, выделить часто задаваемые вопросы и дать на них самый доступный ответ. Подразделы: «FAQ» и «Устранение типовых проблем»
Вспомогательная и юридическая информация. Здесь вы размещаете информацию о компании, размещаете контактные данные тех.поддержки, информацию о сотрудничестве, сайт, а также лицензионные соглашения.
Названия проекта публиковать не будем, Хабр ругается.
P.S. Мы будем рады, если наши образцы помогут вам закрыть вопрос и успешно реализовать документацию в своем проекте.
Примеры и рекомендации удобных инструкций
Снова здравствуй, уважаемый хабралюд!
В продолжении своего поста решил написать, как лучше всего создавать инструкции для пользователей и администраторов.
Всем, кому интересно, прошу под хабракат.
Принцип 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,
Источник
Как написать руководство пользователя программы или сайта — инструкции, советы, помощь, программное обеспечение
Журавлев Денис
Что такое руководство пользователя и для чего его создавать
Ежедневно создаются новые продукты, программы, сервисы и часто пользователям приходится несладко при освоении какой-нибудь сложной программы, поэтому каждому новому продукту желательно собственное руководство. Для чего?
Большинство людей не хочет разбираться с чем-то незнакомым без персонального, всегда доступного и понятного помощника. А именно им и является хорошее руководство пользователя.
Общие советы по созданию пользовательской документации
Перед тем как приступить к созданию руководства, нужно определиться с некоторыми важными моментами. Например, определить, для кого вы его пишете? Кто его будет читать — рядовые пользователи, для которых важны базовые функции продукта, или люди, которым нужны особые, нечасто используемые функции программы/сервиса.
После этого важно подумать о том:
- Где пользователь будет к нему обращаться: дома, на работе, в машине?
- Как часто он будет его просматривать?
- Насколько объективно сложен для понимания продукт?
Из этого можно сделать вывод, насколько интенсивно пользователь будет работать с документацией, а значит уже можно выбрать между сжатым «справочником» или объемным «путеводителем» Также важно, чтобы руководство писал профессионал, знающий продукт. Так что по возможности делегируйте написание техническому специалисту или аналитику, у которого есть полное представление о всех тонкостях продукта.
Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте — не сделает ли полное отсутствие терминов ваше руководство бесполезным?
Структура руководства пользователя
После того как вы ответили на предыдущие вопросы, создайте структуру руководства. У любого хорошего «путеводителя» хорошая и логичная структура. Начните с оглавления. Информативное содержание поможет читателю легко ориентироваться в документе.
В первом разделе желательно рассказать общую информацию о программе:
- Для чего создан продукт.
- Какие задачи он решает.
- Какие основные выгоды от использования для клиента.
В следующем разделе можно указать основные элементы пользовательского интерфейса. Пользователю будет трудно разобраться в софте, если он не поймёт для чего служат различные элементы интерфейса, или он не разберётся в основных режимах работы ПО. Опишите понятным языком предназначение экранов и окон.
Создайте раздел, где расскажете о наиболее эффективных способах применения продукта для решения типовых задач. Какие цели стоят перед клиентом, и как ваша программа/сервис помогает достичь их. Укажите информацию о том, как быстро и продуктивно пользоваться программой.
Ни одно руководство не обойдется без таких разделов как: «Частые вопросы» и «Устранение типовых проблем» В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.
Иногда технические писатели забывают о важном моменте в руководстве пользователя — контактная информация. Этот раздел поможет пользователям связаться с вами, даже если у них нет никаких вопросов и руководство полностью закрывает все их потребности. Клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Инструменты для быстрого создания руководства пользователя
Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в 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 — инструмент для создания мобильной версии пользовательской документации к программным продуктам
- Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний — бесплатные шаблоны и примеры пользовательской документации