Одним из пунктов при тестировании новшества является проверка Хелпа. А какие пункты можно и стоит включить в чек-лист, чтобы Хелп действительно помогал пользователю?
Под Хелпом ПО подразумеваются несколько его вариаций: ReadMe/FirstRead файл в составе инсталлятора, отдельная документация типа "Руководство пользователя", встроенная справка типа Online Help, Instant Help и Hint, краткий список изменений в конкретном билде/версии типа Release Notes.
Первоочередная задача Хелпа - помощь в освоении и последующем использовании продукта. Инструкцию юзер должен логко воспринимать и желательно быстро пошагово применять. Говорят, что хорошо сделанное интерфейсное ПО интелектуально-доступное и не нуждается в хелпе. Но поскольку у каждого пользователя свой взгляд на всё, то Хелп нужен даже для самого понятного окна и его элементов. Поэтому предлагаю вам универсальный чек-лист для проверки Хелпа десктопного продукта в OS Windows. Он сформировался из многолетнего собственного опыта в качестве программиста, QA, сотрудника техподдержки и аналитика.
1. Наличие
1.1. Инсталлятор продукта имеет самостоятельный Хелп, не встроенный в инсталлируемый продукт, с подробными пунктами о системных требованиях для установки, шагами установки и утилизации продукта.
1.2. После установки продукта или его первого запуска доступен полный Хелп продукта.
1.3. Вызываемые из продукта внешние программы имеют самостоятельный Хелп от провайдера. Опционально.
1.4. Элементы окна с обязательным хинтом (кнопки, ссылки, иконки/картинки, обрезанные тексты) показывают его после наведения курсора.
1.5. Диалоговое окно с пояснительным текстом открывается по нажатию кнопки Instant Help.
2. Функционирование
2.1. Каждый интерфейсный элемент и функция программы имеет описание в Хелпе, который доступен по нажатию общепринятой горячей клавиши F1, если её замена не предусмотрена настройками продукта.
2.2. Место вызова внешней программы описано и связано с соответствующей статьёй Хелпа. Внешняя программа с собственным Хелпом открывает собственный Хелп, не путая его с основной программой.
2.3. Внутренние ссылки Хелпа открывают статьи в соответствии с наименованием.
2.4. В Хелпе возможен поиск по наименованию элемента окна и функциональности продукта.
2.5. Элементы окна с обязательным Хинтом показывают его спустя секунд после наведения курсора и оставляют видимым в течение секунд или до сдвига курсора.
2.6. Диалоговое окно с Instant Help открывается и закрывается по нажатию соответветствующих кнопок или горячих клавиш.
2.7. Для работы с Хелпом в режиме просмотра, если иное (правка статей, запуск иных продуктов из тела Хелпа) не предусмотрено основным продуктом, установлено достаточное количество вспомогательных продуктов, либо они входят в инсталлятор основного приложения.
2.8. Ожидаемое отображение картинок (масштабирование, размер, формат, скорость показа, внешний вьювер) и специальных символов (региональные настройки продукта и OS, компилированный/форматированный Хелп).
2.9. Стресс-тест: отсутствие переполнения буфера после вызова всех статей Хелпа несколько раз, перезапуск дополнительного окна/приложения/библиотеки для Хелпа в одном или нескольких сеансах основного приложения.
2.10. Ограниченность вызова справки в скрытом режиме работы основного приложения.
3. Полноценность и актуальность содержимого
3.1. Структура Хелпа соответствует требованиям ГОСТ 19 или ГОСТ 34 или IEEE Std 1063-2001.
3.2. Статьи внутри-продуктовых модулей в достаточной мере рассказывают о работе внешних дополнительно-исполняемых подпрограмм, используемых библиотек или ссылки на их документацию имеются и актуальны (соответствующая версия, локализация).
3.3. В Глоссарии перечислены термины, аббревиатуры, иконки приложения и Хелпа. Для каждого элемента имеется несколько статей Хелпа.
3.4. Подробно описаны функциональности продукта и элементы окна: расположение, путь доступа/активации, предназначение, варианты использования, возможные исключения, слинкованы с дополнительными статьями Хелпа.
3.5. Обновление содержимого статей и структуры Хелпа соответствует версии продукта.
3.6. В Хелпе имеется информация: описание продукта, способы установки и утилизации, системные и лицензионные требования, описания интерфейса и функциональностей, стандартные варианты использования и исключения, способы настройки, ссылки на дополнительную инфу.
4. Usability
4.1. Текст имеет ссылки на логически и функционально связанные статьи Хелпа, внешних профессионалов, community продукта.
4.2. Для каждой функциональности имеется пример с подробными шагами и скриншотами.
4.3. Интерфейсные окна и элементы описаны в статьях не только словами, но и картинками. Примечание: содержимое картинок достаточное, но не избыточное.
4.4. Проблемные ситуации описаны в особом блоке каждой статьи и в отдельном блоке всего Хелпа.
4.5. При воспроизведении проблемы в приложении имеется автозапуск Хелпа и локация на соответствующем совете о разрешении проблемы, либо перенаправление в техподдержку.
4.6. Сообщение об ошибке имеет достаточное пояснение по её недопущению в следующий раз.
4.7. Форматирование текста: видимые заголовки, подсвеченные основные термины, линки на связанные статьи из текущего текста, одинаковая структура статей (заголовок, введение, основная часть, примеры, исключения, дополнения), нумерация шагов, структурирование списков, место картинок (в тексте или выделенной панели).
4.8. Короткие предложения, абзацы, статьи. Примеры и дополнения в отдельных статьях. Сворачиваемость древовидных списков.
5. Грамотность и региональная локализация
5.1. Технические термины имеют словарь толкований для низкоподготовленного пользователя отдельно от Глоссария.
5.2. Технологически-грамотно описаны процессы и интерфейс.
5.3. Лингвистика соответствует региональной локализации: структура предложений, синтаксическая и пунктуационная грамотность, стандарты наименований. Корпоративные исключения описаны в отдельной статье Хелпа "Как использовать данный документ".
5.4. Стиль текста и форматирования соответствует технической сфере.
5.5. Отсутствуют недоправки дубляжа. Подробные описания элементов и терминов состоят не только из синонимов, но и подсказывают варианты использования этого компонента.
5.6. Каждая статья Хелпа отвечает на вопросы "Что это?", "Где найти?" или "Как запустить?", "Зачем это всё здесь?" или "Как с этим управляться?"
Для создания правильного Хелпа можете почитать:
Под Хелпом ПО подразумеваются несколько его вариаций: ReadMe/FirstRead файл в составе инсталлятора, отдельная документация типа "Руководство пользователя", встроенная справка типа Online Help, Instant Help и Hint, краткий список изменений в конкретном билде/версии типа Release Notes.
Первоочередная задача Хелпа - помощь в освоении и последующем использовании продукта. Инструкцию юзер должен логко воспринимать и желательно быстро пошагово применять. Говорят, что хорошо сделанное интерфейсное ПО интелектуально-доступное и не нуждается в хелпе. Но поскольку у каждого пользователя свой взгляд на всё, то Хелп нужен даже для самого понятного окна и его элементов. Поэтому предлагаю вам универсальный чек-лист для проверки Хелпа десктопного продукта в OS Windows. Он сформировался из многолетнего собственного опыта в качестве программиста, QA, сотрудника техподдержки и аналитика.
1. Наличие
1.1. Инсталлятор продукта имеет самостоятельный Хелп, не встроенный в инсталлируемый продукт, с подробными пунктами о системных требованиях для установки, шагами установки и утилизации продукта.
1.2. После установки продукта или его первого запуска доступен полный Хелп продукта.
1.3. Вызываемые из продукта внешние программы имеют самостоятельный Хелп от провайдера. Опционально.
1.4. Элементы окна с обязательным хинтом (кнопки, ссылки, иконки/картинки, обрезанные тексты) показывают его после наведения курсора.
1.5. Диалоговое окно с пояснительным текстом открывается по нажатию кнопки Instant Help.
2. Функционирование
2.1. Каждый интерфейсный элемент и функция программы имеет описание в Хелпе, который доступен по нажатию общепринятой горячей клавиши F1, если её замена не предусмотрена настройками продукта.
2.2. Место вызова внешней программы описано и связано с соответствующей статьёй Хелпа. Внешняя программа с собственным Хелпом открывает собственный Хелп, не путая его с основной программой.
2.3. Внутренние ссылки Хелпа открывают статьи в соответствии с наименованием.
2.4. В Хелпе возможен поиск по наименованию элемента окна и функциональности продукта.
2.5. Элементы окна с обязательным Хинтом показывают его спустя
2.6. Диалоговое окно с Instant Help открывается и закрывается по нажатию соответветствующих кнопок или горячих клавиш.
2.7. Для работы с Хелпом в режиме просмотра, если иное (правка статей, запуск иных продуктов из тела Хелпа) не предусмотрено основным продуктом, установлено достаточное количество вспомогательных продуктов, либо они входят в инсталлятор основного приложения.
2.8. Ожидаемое отображение картинок (масштабирование, размер, формат, скорость показа, внешний вьювер) и специальных символов (региональные настройки продукта и OS, компилированный/форматированный Хелп).
2.9. Стресс-тест: отсутствие переполнения буфера после вызова всех статей Хелпа несколько раз, перезапуск дополнительного окна/приложения/библиотеки для Хелпа в одном или нескольких сеансах основного приложения.
2.10. Ограниченность вызова справки в скрытом режиме работы основного приложения.
3. Полноценность и актуальность содержимого
3.1. Структура Хелпа соответствует требованиям ГОСТ 19 или ГОСТ 34 или IEEE Std 1063-2001.
3.2. Статьи внутри-продуктовых модулей в достаточной мере рассказывают о работе внешних дополнительно-исполняемых подпрограмм, используемых библиотек или ссылки на их документацию имеются и актуальны (соответствующая версия, локализация).
3.3. В Глоссарии перечислены термины, аббревиатуры, иконки приложения и Хелпа. Для каждого элемента имеется несколько статей Хелпа.
3.4. Подробно описаны функциональности продукта и элементы окна: расположение, путь доступа/активации, предназначение, варианты использования, возможные исключения, слинкованы с дополнительными статьями Хелпа.
3.5. Обновление содержимого статей и структуры Хелпа соответствует версии продукта.
3.6. В Хелпе имеется информация: описание продукта, способы установки и утилизации, системные и лицензионные требования, описания интерфейса и функциональностей, стандартные варианты использования и исключения, способы настройки, ссылки на дополнительную инфу.
4. Usability
4.1. Текст имеет ссылки на логически и функционально связанные статьи Хелпа, внешних профессионалов, community продукта.
4.2. Для каждой функциональности имеется пример с подробными шагами и скриншотами.
4.3. Интерфейсные окна и элементы описаны в статьях не только словами, но и картинками. Примечание: содержимое картинок достаточное, но не избыточное.
4.4. Проблемные ситуации описаны в особом блоке каждой статьи и в отдельном блоке всего Хелпа.
4.5. При воспроизведении проблемы в приложении имеется автозапуск Хелпа и локация на соответствующем совете о разрешении проблемы, либо перенаправление в техподдержку.
4.6. Сообщение об ошибке имеет достаточное пояснение по её недопущению в следующий раз.
4.7. Форматирование текста: видимые заголовки, подсвеченные основные термины, линки на связанные статьи из текущего текста, одинаковая структура статей (заголовок, введение, основная часть, примеры, исключения, дополнения), нумерация шагов, структурирование списков, место картинок (в тексте или выделенной панели).
4.8. Короткие предложения, абзацы, статьи. Примеры и дополнения в отдельных статьях. Сворачиваемость древовидных списков.
5. Грамотность и региональная локализация
5.1. Технические термины имеют словарь толкований для низкоподготовленного пользователя отдельно от Глоссария.
5.2. Технологически-грамотно описаны процессы и интерфейс.
5.3. Лингвистика соответствует региональной локализации: структура предложений, синтаксическая и пунктуационная грамотность, стандарты наименований. Корпоративные исключения описаны в отдельной статье Хелпа "Как использовать данный документ".
5.4. Стиль текста и форматирования соответствует технической сфере.
5.5. Отсутствуют недоправки дубляжа. Подробные описания элементов и терминов состоят не только из синонимов, но и подсказывают варианты использования этого компонента.
5.6. Каждая статья Хелпа отвечает на вопросы "Что это?", "Где найти?" или "Как запустить?", "Зачем это всё здесь?" или "Как с этим управляться?"
Для создания правильного Хелпа можете почитать:
- ГОСТ 19.402-78 ЕСПД. Описание программы
- ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению
- ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению
- ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению
- ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.
- ГОСТ 34.602-89 Техническое задание на создание автоматизированной системы
- ГОСТ 34.201-89 Виды, комплектность и обозначения документов при создании автоматизированных систем
- РД 50-34.698-90 Автоматизированные системы. Требования к содержанию документов
- IEEE Std 1063-2001 Standard for Software User Documentation
- http://www.it-gost.ru/content/view/94/51/
- http://tdocs.su/1391
- http://technicaldocs.ru/гост34/шаблоны/руководство_пользователя
- https://www.drexplain.ru/articles/razrabotka_rukovodstva_polzovatelya_po_gost_34_i_gost_19_v_programme_dr_explain/
- http://ddd.exmachina.ru/content/how_to_make_good_userguide/
- https://habr.com/post/153973/
"Сообщения об ошибках — тоже документация, тестируйте их!" (https://okiseleva.blogspot.com/2015/06/blog-post_8.html) - подсказки от О.К. (Киселёвой-Назиной).
ОтветитьУдалить