Что может входить в документацию пользователя
Документация пользователя
Документация пользователя (user documentation): полный комплект документов, поставляемых в печатном или другом виде, который обеспечивает применение продукта, а также является его неотъемлемой частью.
Документация пользователя должна отвечать следующим характеристикам.
Полнота (completeness). Документация пользователя должна содержать информацию, необходимую для использования продукта. В ней должны быть полностью описаны все функции, установленные в описании продукта, и все вызываемые пользователем функции из программы. Кроме того, граничные значения, заданные в описании продукта, должны быть продублированы в документации пользователя. Если установка (инсталляция) продукта может быть проведена пользователем, то в документацию пользователя должно быть включено руководство по установке продукта, содержащее всю необходимую информацию. Если сопровождение продукта может проводиться пользователем, то в документацию пользователя должно быть включено руководство по сопровождению программы, содержащее всю информацию, которая необходима для обеспечения данного вида сопровождения.
Правильность (correctness). Вся информация в документации пользователя должна быть правильной. Кроме того, представление данной информации не должно содержать неоднозначных толкований и ошибок.
Непротиворечивость (consistency). Документы, входящие в комплект документации пользователя, не должны противоречить сами себе, друг другу и описанию продукта. Каждый термин должен иметь один и тот же смысл во всех документах.
Понятность (understandability). Документация пользователя должна быть понятной для сообщества пользователей, выполняющих указанную рабочую задачу, например, посредством использования в ней соответствующим образом подобранных терминов, графических вставок, уточняющих пояснений и путем ссылок на полезные источники информации.
Простота обозрения (ease of overview). Документация пользователя должна быть достаточно проста для изучения пользователем, чтобы он мог выявить все описываемые в ней взаимосвязи компонентов продукта. В каждый документ могут быть включены оглавление и предметный указатель.
Резюмируя, скажем, что возникла настоятельная потребность во введении в отечественные стандарты на документирование ПС тех норм, правил, требований и рекомендаций, которые установлены на международном и передовом зарубежном уровнях. Но при проведении этих работ нельзя ограничиваться прямым переводом отдельных международных стандартов. Нужно, чтобы новые стандарты правильно стыковались со всем имеющимся и будущим множеством нормативных документов.
Как мы в «Активе» пишем пользовательскую документацию. Почему это важно
Что пользователь хочет видеть в пользовательской документации? Что его в ней раздражает? Эти вопросы задаёт себе каждый, кто пишет такую документацию, но далеко не каждый правильно отвечает на них. Совсем небольшой процент пользователей читает документацию. Давайте разберёмся, почему так и как сделать пользовательскую документацию эффективной и изменить отношение пользователей к ней.
Нам мешает негативный опыт
С такой ситуацией сталкивался почти каждый: вам надо быстро освоить какую-то ИТ-систему, она очень сложная, и в ней хранятся важные данные. Метод “проб и ошибок” здесь не подойдёт. Наверняка в такой момент вы вспомнили про руководство пользователя, открыли его и начали внимательно изучать. После 10 минут чтения вы ещё больше запутались, закрыли руководство и начали осваивать систему, используя при этом метод “будь что будет”. И хорошо, если при этом вы не удалили что-то очень важное и не получили результат, о котором будете жалеть, а ведь всякое бывает.
Да, через какое-то время вы всё-таки освоили систему и ловко жонглируете её процедурами, но чего это вам стоило? Вы потратили время, нервы и может даже не только свои. Что решило бы вашу проблему ещё на раннем этапе?
Ответ один — хорошая пользовательская документация.
Документация может всё
Пользовательская документация не только помогает быстро разобраться в ИТ-системе, она формирует позитивный пользовательский опыт и тем самым укрепляет репутацию продукта и компании в целом. Но не стоит забывать и о противоположной ситуации: плохая пользовательская документация помешает пользователю разобраться в ИТ-системе, сформирует негативный опыт и разрушит репутацию продукта и компании. Верю, что эта мысль понятна всем и здесь ничего не надо объяснять.
Давайте представим, что у вас уже есть документация. Вы видите, что пользователи её просматривают. Наряду с этим, количество звонков в техподдержку не уменьшается, и пользователи чаще всего спрашивают о том, что уже давно описано в документации. Почему так? Причин может быть много, я разберу только те, которые связаны именно с пользовательской документацией.
Это будет цикл статей, в которых я расскажу вам про основные ошибки в технической документации, мы посчитаем, сколько они стоят компании. Я объясню поведение пользователя, обозначу, с какими трудностями и эмоциями он сталкивается, когда читает плохой документ. Покажу, как можно исправить ошибки с минимальными затратами. Мои статьи для всех, кто пишет документацию и хочет делать это более осознанно, с заботой о пользователе. Если вы хоть в чем-то будете со мной не согласны, то пишите свои мысли в комментариях. Мы вместе можем сделать эту статью максимально полезной.
Процесс документирования в каждой компании выстроен по-своему. Где-то есть отдел технических писателей, отдел редакторов, отдел локализации технической документации, а где-то всю техническую документацию пишет один технический писатель. Но не стоит забывать о том, что написание документации – это всегда командная работа.
В этой статье я расскажу вам о том, сколько в нашей компании стоит пользовательская документация, и из каких этапов у нас состоит процесс документирования. Let’s go!
Сколько стоит пользовательская документация
Документация стоит денег, давайте разберёмся каких. Если в компании есть технический писатель, то стоимость документации не измеряется только его заработной платой. Расскажу, почему это так.
Рассмотрим на примере инструкции, которую можно написать за 20 часов. Технический писатель за это время напишет 25-страничный документ, в котором будет около 40 скриншотов.
Весь процесс производства инструкции в нашей компании состоит из следующих этапов:
1. Поставка задачи. Её создаёт и описывает менеджер проекта, руководитель проекта или руководитель отдела. На это нужно время, недостаточно просто написать “Опиши процедуру”. Здесь обязательно нужны детали. Например, здесь посчитаем 1 час рабочего времени менеджера проекта. На этапе постановки задачи менеджер проекта назначает консультанта и обозначает круг сотрудников компании, которые могут помочь и объяснят какие-то важные особенности системы. Получается, что цель этого этапа — сформулировать задачу и назначить консультанта
2. Показ системы. Чаще всего здесь задействован системный аналитик, он демонстрирует систему техническому писателю и рассказывает, что и как работает. Прибавим 2 часа работы аналитика + 2 часа технического писателя. Здесь аналитик рассказывает, а технический писатель слушает и задаёт вопросы. Если система сложная, таких встреч может быть несколько. Цель этого этапа — объяснить техническому писателю, как работает система.
3. Написание документа. Здесь главную роль играет технический писатель, но нельзя забывать про вопросы, которые у него могут возникать в процессе написания. Отвечать на них может аналитик, разработчик, менеджер проекта, тот, кто разбирается в продукте и умеет понятно объяснять. Таких вопросов может быть много и хорошо, если технический писатель оперативно получает на них ответы. Прибавим 20 часов работы технического писателя + 1 час работы аналитика + 1 час работы разработчика. Цель этого этапа — создать первую версию инструкции.
4. Рецензирование. Чаще всего читает документ заказчик, в нашем случае — менеджер проекта. На это тоже нужно время, оно зависит от количества страниц в документе и качества описаний. Прибавим 2 часа работы менеджера проекта. На этом этапе он пишет комментарии к документу. Цель этого этапа — проверить документ.
5. Внесение правок. Реализует технический писатель, на этом этапе он тоже может задавать уточняющие вопросы коллегам. Техническому писателю здесь очень важно правильно понять комментарии к инструкции. Прибавим 2 часа работы технического писателя + 1 час работы аналитика. Цель этого этапа — создать вторую версию документа.
6. Тестирование. На этом этапе подключается сотрудник отдела тестирования. Он реализует все описания процедур и оценивает насколько корректно они описаны. Прибавим здесь 2 часа работы тестировщика. Цель этого этапа — проверить корректность описания процедур.
7. Повторное внесение правок. Технический писатель получает от тестировщика комментарии и вносит изменения в инструкцию. Прибавим 1 час работы технического писателя. Цель этого этапа — создание третьей версии документа.
8. Вёрстка документа. Здесь может подключаться дизайнер. Если вёрстка не очень сложная, то технический писатель делает её сам. Прибавим 4 часа работы дизайнера. Цель этого этапа — сверстать документ так, чтобы его было удобно использовать.
9. Публикация документа. Мы публикуем документ на своём сайте на специальной странице. Прибавим 20 минут работы администратора сайта.
Итого:
Получается, что в нашей компании в процессе документирования задействованы 7 человек. У каждого есть своя роль в этом процессе и нельзя сказать, что кто-то менее или более важен. В вашей компании этот процесс может строиться иначе.
После такого подробного разбора наверняка стало понятно, почему стоит учитывать не только заработную плату технического писателя при оценке стоимости пользовательской документации.
100 тысяч рублей или долларов
Вы видите, что технический писатель не один участвует в создании инструкции. Здесь не обязательно называть какие-то точные цифры. Документация стоит денег и ошибки в ней — тоже. Именно поэтому её нужно сразу писать так, чтобы она решала задачи пользователя, приносила ему пользу, а не была чем-то бесполезным и просто “пылилась на полке”.
Сейчас, если в любом поисковике ввести слова “руководство пользователя”, то за 5 минут просмотра результатов вы найдёте как минимум 5 плохих документов и один хороший, а это совсем мало. Получается, что только каждый шестой документ является эффективным, а представьте сколько времени, денег потрачено впустую и надо здесь что-то менять. Давайте делать это вместе, так будет проще обратить внимание всех на эту проблему.
В следующей статье я расскажу про ошибки в документации. Отвечу на вопросы:
Часть I. Документация пользователя (ОБ)
Часть I Документация пользователя (ОБ)
Назначением документации пользователя является обеспечение конечного пользователя достаточной информацией для ясного понимания:
a) цели, функций и характеристик программного средства;
b) того, как ввести в действие и использовать программное средство;
c) договорных прав и обязанностей.
Документация пользователя должна включать в себя справочную документацию для повседневного использования с программой. Дополнительно может быть включена учебная документация, предназначенная для обучения пользователей применению программного средства. Документация может также включать в себя проспекты, буклеты или экранную информацию, дающие обобщенные сведения о рабочих инструкциях и командах.
При необходимости к документации могут быть выпущены дополнения, например:
— список опечаток в документации;
— список установленных, но не исправленных ошибок в программной продукции с описанием известных последствий.
Документация может быть поставлена как в виде твердой копии, так и на электронных или прочих носителях.
6 Справочная документация (ОБ)
Справочная документация должна давать достаточно ясные и исчерпывающие сведения, позволяющие конечному пользователю успешно выбирать, вводить в действие и использовать программное средство.
В соответствующих местах должны быть даны примеры и иллюстрации и определены любые аббревиатуры и символы, использованные в справочной документации.
Должны быть также включены указания по использованию справочной документации.
6.1 Обозначение пакета (ОБ)
6.1.1 Наименование и код пакета (ОБ)
Должны быть приведены имя или заголовок, которым обозначен пакет, и подзаголовок, который указывает его функции. Должен быть также приведен код продукции или справочный номер пакета.
Должно быть приведено дополнительное обозначение для любого пакета, имеющего два или более текущих варианта (например, для различного оборудования или операционной системы).
Должно быть приведено обозначение версии программного средства, при необходимости, вместе с разъяснением системы нумерации версий.
Должны быть приведены даты публикации оригинала и текущей версии.
6.1.5 Изготовитель или торгующая организация (ОБ)
Должны быть приведены наименование и адрес изготовителя или организации, продающей программный пакет.
6.1.6 Ключевые слова (ФАК)
Должны быть приведены ключевые слова или дескрипторы, которые характеризуют пакет и могут быть использованы для составления указателей или в целях поиска. Например, «обработка текстов», «широкоформатная таблица», «управление базой данных», «имитационная модель».
Должен быть определен язык, используемый для интерфейса пользователя программы и для документации пользователя (например, японский, французский, английский).
6.2 Компоненты пакета (ОБ)
6.2.1 Поставляемые элементы (ОБ)
Должны быть перечислены и обозначены по наименованиям и количеству все физические элементы пакета (например, диски, кассеты, руководства и т.д.).
При необходимости, должно быть определено содержание физических элементов (например, программное обеспечение на дисках или кассетах, документы, включенные в руководства, и т.д.).
6.2.2 Сопутствующие объекты (УСЛ)
Должны быть кратко описаны любые сопутствующие программы, аппаратура или документация, которые могут быть необходимы, но не включены в состав пакета. Должны быть также определены условия поставки и серийный номер любого такого объекта.
6.3 Функциональное описание программного средства (ОБ)
6.3.1 Назначение и область применения (ОБ)
Должны быть описаны назначение программного средства и выполняемые им функции. Должны быть пояснена область действия этих функций и, при необходимости, определены любые связанные функции, которые не реализуются. Должны быть описаны назначение и функция(и) каждой составляющей программы, если программное средство состоит из более чем одной программы.
Должны быть даны примеры области применения программного средства.
При необходимости, должны быть описаны специфические и отличительные особенности программного средства, планируемые в будущем его модернизации и т.д.
6.3.2 Условия эксплуатации (ОБ)
а) Требования к техническим средствам (ОБ)
Должна быть определена конфигурация(и) технических средств, необходимых для прогона программного средства, включая требования к памяти. При необходимости должна быть дана ссылка на соответствующую документацию.
b) Требования к программным средствам (УСЛ)
Должны быть определены наименования, варианты, версии и даты любых других программных средств, необходимых для прогона данной программы, со ссылкой на соответствующую документацию.
c) Требования к коммуникациям (УСЛ)
Должны быть определены связные интерфейсы с другими системами.
Должен быть определен используемый протокол и дана любая необходимая взаимосвязанная информация.
Должны быть определены используемый набор символов или коммуникационный код и указаны любые исключения или специальные коды.
d) Другие требования (УСЛ)
Должны быть описаны любые другие требования к условиям эксплуатации.
6.3.3 Характеристики (УСЛ)
a) Рабочие характеристики (УСЛ)
Должна быть приведена количественная информация для типовых примеров, такая как данные о производительности и уровне точности.
b) Размер программы (ФАК)
Должен быть установлен общий размер программы в общепринятых единицах (например, байтах, строках исходного кода).
c) Скорость обработки (ФАК)
Должна быть представлена информация о скорости обработки (например, скорость компиляции, время сортировки, скорость обмена, время поиска, время отклика).
6.3.4 Ограничения (УСЛ)
Должны быть определены любые ограничения по использованию программного средства или его компонентов.
Должно быть указано, защищено ли программное средство от копирования.
Должны быть описаны любые защитные средства, позволяющие пользователю защищать программное средство или его компоненты и данные от несанкционированного доступа.
Должны быть также описаны любые способы проверки и средства дублирования данных.
6.4 Ввод в действие программного средства (ОБ)
6.4.1 Ввод в действие (ОБ)
Должна быть приведена любая необходимая информация о вводе в действие программного средства конечным пользователем, описывающая все действия, необходимые для ввода программного средства в его рабочее окружение, например подключение принтера, ввод спецификации принтера, ввод главного файла, прогон текстовой программы.
6.4.2 Создание дублирующих копий (УСЛ)
Должно быть приведено описание того, как создавать дублирующие копии программного средства, если дублирующие копии допускаются.
6.4.3 Модификация программного средства (УСЛ)
Если пользователь имеет возможность изменять программное средство под свое рабочее окружение или потребности, необходимая информация об этом должна быть приведена.
6.5 Использование программного средства (ОБ)
Должна быть приведена полная информация об использовании программного средства, охватывающая:
a) подготовку к использованию;
b) входные команды и данные;
c) функции программного средства;
d) вывод результатов;
e) сообщения об ошибках и отказах, корректирующие и восстанавливающие действия. Подготовка, ввод, обработка, вывод и ошибки могут быть описаны пофункционально или объединенно, как удобнее.
Должны быть приведены типовые примеры, помогающие пользователю понять работу программного средства, включая образцы листингов и экранных изображений данных и результатов.
6.5.1 Загрузка программного средства (ОБ)
Должны быть приведены инструкции по загрузке программного средства в ЭВМ. Когда требуются предварительные действия, такие как загрузка операционной системы, должны быть приведены соответствующие инструкции или дана ссылка на соответствующую документацию.
6.5.2 Управляющие инструкции, команды или языковые правила (ОБ)
a) Управляющие инструкции и команды (ОБ)
Должны быть четко определены форматы и функции всех управляющих инструкций или команд. Должны быть также определены любые ограничения по их применению, такие как режим работы, условия ввода и последовательности ввода.
b) Выходные сообщения (ОБ)
Должен быть указан список сообщений, отображаемых в ответ на управляющие инструкции или команды. Если сообщения не являются самоочевидными, их значения должны быть описаны. Должны быть также описаны любые действия, предпринимаемые пользователем в ответ на сообщения.
c) Правила языка программирования (УСЛ)
Для компиляторов должны быть описаны правила языка путем ссылки на соответствующую документацию (например ИСО 7185 для языка ПАСКАЛЬ).
a) Входные данные (УСЛ)
Должны быть описаны содержание, логическая структура и формат входных данных, включая значение каждого элемента. Должна быть также описана любая зависимость данных от индивидуальных особенностей носителя данных.
Если требуются другое оборудование или программные средства для подготовки входных данных к программе, например для создания файлов, требования к ним должны быть полностью определены.
b) Вспомогательные данные (УСЛ)
Должны быть описаны любые вспомогательные данные, требуемые для работы программного средства, например словарь для программы обработки текста.
c) Выходные данные (ОБ)
Должны быть описаны содержание и формат экранных изображений, печатных форм и любых других форм выходных данных. Должны быть приведены иллюстрации шаблона вывода.
d) Промежуточные данные (УСЛ)
Для понимания пользователем работы программного средства, при необходимости, должны быть описаны содержание и формат любых промежуточных данных.
e) Ограничения на данные (УСЛ)
Должны быть описаны любые ограничения на данные, например предел по числу разрядов.
f) Хранение данных (УСЛ)
Для понимания пользователем работы программного средства, при необходимости, должны быть описаны форматы файла и записей. Должно быть установлено, позволяют ли условия форматирования использовать файлы и записи других программных средств.
Должны быть описаны любые ограничения, например максимальное число записей на файл, максимальное число файлов на диск.
При необходимости, должно быть приведено, для понимания пользователем работы программы, краткое описание функций, выполняемых программным средством в ответ на входные команды, инструкции и данные.
6.5.5 Ошибки и сбои (ОБ)
Должны быть описаны все ошибочные и сбойные ситуации и соответствующие сообщения. Должны быть также приведены все корректирующие действия по всем ошибкам и сбоям.
6.6 Техническая информация о программном средстве (УСЛ)
Для некоторых типов пакетов, например программных средств научного назначения, может быть необходимым представление технической информации о программе, например используемый язык, структура программного средства, используемый алгоритм.
Должен быть точно определен язык программирования, преимущественно путем ссылки на соответствующий стандарт, если пользователю необходима эта информация, например для объединения пакета с другим программным средством. Дополнительно должны быть приведены наименование, вариант, версия и поставщик компилятора или интерпретатора.
Должно быть установлено, приняты ли какие-либо исключения для стандарта на язык.
6.6.2 Принципы и алгоритмы решения задач (ФАК)
Должны быть описаны теоретические принципы, методы решения и алгоритмы, использованные в связи с определенными функциями и со структурной организацией программы. Должны быть приведены ссылки на соответствующую литературу.
Должны быть приведены уточнения любых специальных представлений символов или сочетаний символов, применяемых при решении задачи, особенно в части префиксов, суффиксов, обозначений, точности, округления, систем координат и диапазона значений.
6.6.3 Структура программного средства (ФАК)
Должна быть описана организация элементов программного средства (например, программ, модулей, сегментов, общих областей памяти).
Представление структуры может быть графическим, например посредством древовидной структурной схемы или путем соответствующего структурированного текстового описания, оно может содержать наименования элементов, их точки входа и интерфейсы, так же как и их взаимосвязи.
6.7 Тестирование (ФАК)
Должны быть описаны любые методы, используемые для тестирования функций программных пакетов, с контрольными примерами входных и ожидаемых выходных данных.
6.8 Договорная информация (ОБ)
6.8.1 Обязательства или гарантии (ОБ)
Должны быть установлены условия авторского права и сроки обязательств или гарантий. Должен быть указан гарант.
6.8.2 Юридические права и обязанности (ОБ)
Должны быть описаны юридические обязанности изготовителя и права потребителя, включая:
a) обучение и соответствующую помощь;
b) поддержку программного средства (исправление ошибок и т.д.);
c) гарантии качества (приемочные испытания и т.д.);
d) доступность исходной программы.
Должен(ны) быть приведен(ы) адрес(а) организации(й) или лица(лиц), ответственных за выполнение вышеперечисленных задач.
6.8.3 Стандарты и законы (ФАК)
Должны быть приведены ссылки на любые примененные стандарты.
Должны быть установлены степень или уровень, до которых следуют стандарту, в случае неполного соответствия ему.
Должен быть приведен словарь технической и другой специальной терминологии, с которой может быть плохо знаком пользователь.
Должен быть приведен указатель состава справочной документации.
6.11 Замечания конечных пользователей (ФАК)
Должны быть приведены способы, с помощью которых конечные пользователи могут делать замечание о точности и полезности документации. Это может быть сделано в форме предварительно отпечатанной, оплаченной для пересылки почтовой карточки, возвращаемой изготовителю или торгующей организации.
7 Учебная документация (ФАК)
Назначением учебной документации является предоставление возможности постепенного введения в работу пакета для новых или неопытных пользователей.
Для простейших типов программных средств этому требованию может достаточно просто удовлетворять состав справочной документации. Однако для программного средства с более сложным интерфейсом пользователя рекомендуется специальная справочная документация.
Так как назначением учебной документации является знакомство пользователей с программным средством, нет необходимости описывать интерфейс пользователя в полном объеме. Должны быть представлены достаточные инструкции для приобретения пользователями опыта и уверенности в использовании программного средства и подведения их к тому моменту, когда они будут в состоянии успешно пользоваться справочной документацией.
В отличие от печатной документации или в дополнение к ней, учебная может быть представлена в режиме работы основного оборудования (например, как программное средство или отдельные данные, поставляемые и загружаемые с диска). Изготовитель, торгующая организация или поставщик также могут предлагать обучение персонала.
8 Быстрая справочная документация (ФАК)
Сводная таблица рабочих инструкций (команд, сообщений об ошибках и т.д.), отпечатанная на карточке или в небольшом буклете, достаточно полезна для опытного пользователя как дополнение к справочной документации.
Также рекомендуется обеспечение экранного меню и средств «помощи».
Откройте актуальную версию документа прямо сейчас или получите полный доступ к системе ГАРАНТ на 3 дня бесплатно!
Если вы являетесь пользователем интернет-версии системы ГАРАНТ, вы можете открыть этот документ прямо сейчас или запросить по Горячей линии в системе.