пятница, 11 марта 2016 г.

Разработка документации пользователя программного продукта (Ю.В. Кагарлицкий) — отзыв на книгу

Как понятно рассказать пользователю о программном продукте? Эта тема мне давно интересна. С целью развития навыков изучил книгу Ю.В. Кагарлицкого "Разработка документации пользователя программного продукта (методика и стиль изложения)".

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


Про постановку задачи

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

Про требования к содержанию

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

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

  • Определить способ изложения – с точки зрения пользовательских задач (руководство) или с точки зрения функций продукта (справочник).
  • Идеальная структура получается в результате правильного баланса между глубиной и сечением:
    • Глубина — до 4-х уровней (раздел, подраздел, пункт, подпункт).
    • Сечение — до 9 элементов (т.е. в разделе — до 9 подразделов, в подразделе — до 9 пунктов, в пункте — до 9 подпунктов). Моё мнение — лучше стремиться к тому, чтобы в сечении было не более 7-ми элементов.
  • Заголовкам структурных элементов, которые не содержат сведения о функционировании, рекомендуется придавать особую форму. Например: «Графические форматы: обзор», «О реляционных базах данных» и т.п.
  • Не рекомендуется начинать несколько пунктов перечисления с одного и того же слова (словосочетания).
  • Маркировать особо: предупреждения, предостережения, советы, примеры, сведения для отдельных групп пользователей.
  • Избегать дробления всего текста на короткие абзацы из 1-2 предложений.
  • Последовательность изложения: сначала пользователь знакомится со структурной информацией, затем – с процедурно-функциональной, и, если сочтет необходимым, со справочной.
  • Список фигур описания — использовать единые фигуры описания в рамках всего документа.
  • Избыток перекрестных ссылок мешает последовательному восприятию текста — использовать только тогда, когда они действительно нужны.

Про слова и формулировки

  • Жаргон недопустим.
  • Термины из предметной области вводятся посредством определения, термины из ИТ – по контексту.
  • Употребление терминов должно быть унифицировано в пределах одного документа и в рамках всего комплекта документации.
  • Зоны риска возникновения неоднозначных формулировок: модальные глаголы и выражения, формы множественного и единственного числа, союзы «и» и «или», деепричастия, возвратные формы глаголов.

Про проблемы изложения материала

Канонический порядок изложения сведений:
  • Программный продукт и формы работы с ним: Установка — Удаление — Настройка — Начало работы (запуск или авторизация) — Завершение работы — Целевое применение продукта — Обслуживание продукта и обрабатываемых данных — Дополнительная настройка.
  • Процесс и его стадии: Общая характеристика процесса и перечисление его стадий — Запуск процесса — Основные стадии процесса в их основной последовательности — Штатное завершение процесса — Способы нештатного завершения процесса.
  • Объект и этапы его жизненного цикла: Объект, его назначение и природа — Свойства объекта и его статуса, обзор жизненного цикла — Создание объекта — Редактирование свойств — Прочие действия с объектом — Удаление объекта.
В дополнение привожу хорошие советы по составлению руководства пользователя от сообщества analyst.by.

Спасибо за внимание.

Комментариев нет:

Отправить комментарий

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

Яндекс.Метрика