Как понятно рассказать пользователю о программном продукте?
Эта тема мне давно интересна. С целью развития навыков изучил книгу
Ю.В. Кагарлицкого "Разработка документации пользователя программного
продукта (методика и стиль изложения)".
В процессе чтения для себя отмечал важные факты, которые привожу
ниже. Может быть, найдете для себя что-то новое и ценное.
Про постановку задачи
- Определить потребности пользователя и выбрать вида документа — справочник с функциями продукта или руководство пользователя с описанием решения пользовательских задач.
- Определить пользовательскую перспективу (набор возможностей, ограничений, рамочных условий взаимодействия с продуктом), на основе которой будет формироваться структура документа.
- Выполнить профилирование документа по адресату, способу чтения, тематике.
Про требования к содержанию
- Содержание определяется главной задачей – обеспечить целевое применение продукта.
- В документации пользователя неуместны положения, которые относятся к служебным обязанностям пользователя.
Про структуру документации пользователя
- Определить способ изложения – с точки зрения пользовательских задач (руководство) или с точки зрения функций продукта (справочник).
- Идеальная структура получается в результате правильного баланса между глубиной и сечением:
- Глубина — до 4-х уровней (раздел, подраздел, пункт, подпункт).
- Сечение — до 9 элементов (т.е. в разделе — до 9 подразделов, в подразделе — до 9 пунктов, в пункте — до 9 подпунктов). Моё мнение — лучше стремиться к тому, чтобы в сечении было не более 7-ми элементов.
- Заголовкам структурных элементов, которые не содержат сведения о функционировании, рекомендуется придавать особую форму. Например: «Графические форматы: обзор», «О реляционных базах данных» и т.п.
- Не рекомендуется начинать несколько пунктов перечисления с одного и того же слова (словосочетания).
- Маркировать особо: предупреждения, предостережения, советы, примеры, сведения для отдельных групп пользователей.
- Избегать дробления всего текста на короткие абзацы из 1-2 предложений.
- Последовательность изложения: сначала пользователь знакомится со структурной информацией, затем – с процедурно-функциональной, и, если сочтет необходимым, со справочной.
- Список фигур описания — использовать единые фигуры описания в рамках всего документа.
- Избыток перекрестных ссылок мешает последовательному восприятию текста — использовать только тогда, когда они действительно нужны.
Про слова и формулировки
- Жаргон недопустим.
- Термины из предметной области вводятся посредством определения, термины из ИТ – по контексту.
- Употребление терминов должно быть унифицировано в пределах одного документа и в рамках всего комплекта документации.
- Зоны риска возникновения неоднозначных формулировок: модальные глаголы и выражения, формы множественного и единственного числа, союзы «и» и «или», деепричастия, возвратные формы глаголов.
Про проблемы изложения материала
Канонический порядок изложения сведений: - Программный продукт и формы работы с ним: Установка — Удаление — Настройка — Начало работы (запуск или авторизация) — Завершение работы — Целевое применение продукта — Обслуживание продукта и обрабатываемых данных — Дополнительная настройка.
- Процесс и его стадии: Общая характеристика процесса и перечисление его стадий — Запуск процесса — Основные стадии процесса в их основной последовательности — Штатное завершение процесса — Способы нештатного завершения процесса.
- Объект и этапы его жизненного цикла: Объект, его назначение и природа — Свойства объекта и его статуса, обзор жизненного цикла — Создание объекта — Редактирование свойств — Прочие действия с объектом — Удаление объекта.
Спасибо за внимание.
Комментариев нет:
Отправить комментарий
Спасибо за проявленный интерес! Буду рад получить обратную связь в виде комментария...