2.2. Стандарты, регламентирующие эксплуатационную документацию программных средств

Эксплуатационная документация должна обеспечивать эффективное применение программных средств в соответствии с их назначением и функциями квалифицированными специалистами-пользователями. Состав и содержание комплекта документов конкретного программного продукта, следует адаптировать разработчиками к его особенностям и свойствам на основе использования стандартов и типовых структур – шаблонов. Разработчики документов должны обеспечивать комфортное и корректное применение ПС пользователями, на основе ясного и непротиворечивого изложения в документах технологических процедур и операций для функционирования и получения требуемых результатов. На базе представленного в стандарте набора и содержания документов следует выделять из них необходимые для двух классов ПС, которые в наибольшей степени различаются особенностями эксплуатации. Первый класс характеризуется комплексами программ автоматизированного управления динамическими объектами и процессами в реальном масштабе времени. В процессе их применения допускается минимальное вмешательство и процедуры пользователей, и необходим, соответственно, небольшой объем эксплуатационных документов, выделяемых из базового комплекта (малый – в таблице 3.7). Для ПС второго класса воз- можно применение пользователями широкого набора процедур управления, которые должны быть регламентированы достаточно полным набором и подробным содержанием документов. Все последующее изложение ориентировано на этот класс ПС и в п. 3.7 представлен широкий набор шаблонов базовых документов (крупный – в таблице 3.7).

Пользователи таких ПС можно разделить на две крупных группы, каждая из которых должна быть обеспечена комплектной эксплуатационной документацией:

- администраторы, подготавливающие ПС к эксплуатации и обеспечивающие их функционирование и использование по прямому назначению;

- операторы – пользователи, реализующие функционирование и применение программных средств в системе, обработку и анализ результатов.

Стандарт ISO 15910 является наиболее современным нормативным документом, регламентирующим процессы создания эксплуатационной документации для пользователей сложных программных средств. Целью стандарта является стимулирование разработчиков программных средств к методичному использованию процесса документирования. Он построен по традиционной схеме стандартов ISO и первые семь разделов являются вводными, а также определяют терминологию. Основное, функциональное содержание стандарта сосредоточено в 8-м разделе – Требования к документированию ПС. В разделе 8.1 – Процессы документирования программных средств – представлена общая схема процессов и их взаимодействие. Изложена детальная структура плана документирования, ориентированного на разработчиков документов, и процедуры контроля реализации плана. Обзоры – описания документов, рекомендуется подготавливать в виде двух последовательно уточняющихся и детализирующихся редакций с окончательной корректурой и проверкой их адекватности путем тестирования. Пользовательская документация должна проходить испытания на достоверность, которые должны быть спланированы и реализованы типовыми пользователями на базе применения эксплуатационных процедур реального программного средства. Описана координация документирования у субподрядчиков, а также конфигурационное управление изменениями и сопровождение документов. Раздел 8.2 посвящен требованиям к содержанию и стилю изложения типовой спецификации. Изложены требования к языку и грамматике составления документов, к оформлению содержания текста, рисунков и таблиц, к характеристикам и качеству используемой бумаги. Подробно описаны технические правила оформления твердой копии документов и правила структурирования и представления схем компонентов, окружения, иллюстраций и основного текста документов. Специальный подраздел посвящен подготовке электронных документов: общей схеме, размещению материала и комментариев, помощи подсказками, навигации по тексту, использованию клавиатуры.

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

Настоящий стандарт определяет реализацию процесса документирования, описанного в ISO 12207 и может быть адаптирован к условиям конкретных проектов. Стандарт не определяет компоновку конкретного документа, его содержание и другие аспекты комплектности документации, однако он устанавливает метод планирования и проведения процессов документирования.

Процесс документирования должен быть выполнен в два этапа. Поэтапные работы выполняются не одновременно. На отдельных этапах работы могут проводиться параллельно. Возможные итерации работ показаны пунктирными линиями. Минимальный состав документации определяется заказчиком (например, с использованием ISO 12207 или ISO 6592), что должно быть учтено документатором при разработке плана документирования.

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

В стандарте ISO 15910 представлено восемь приложений, содержащих примеры и расширяющих некоторые концепции базовой части стандарта: Приложение А. Перекрестные ссылки с стандартом ISO 12207.

Приложение В. Использование настоящего стандарта в договоре и практическое применение настоящего стандарта.

Приложение С. Образец плана документирования. Документация пользователя для системы ABC:

С.1. Введение

С.2. Область применения и ограничения

С.З. Оформление и стиль описания

С.4. Аудитория

С. 5. Проект содержания документации

С. 6. Номенклатура поставки

С.7. Авторские права

С.8. Транспортирование

С.9. Процесс разработки и контроль

С. 10. Тиражирование

С. 11. Проектанты

С. 12. Ресурсы

С. 13. Тестирование на практичность

С. 14. График работ

Приложение D. Отношения между аудиториями, выданными заданиями, бумажной и диалоговой документацией.

Приложение Е. Рекомендации по написанию на английском языке документации, подлежащей последующему переводу.

Приложение F. Оценка ресурсов для проекта документирования. Приложение G. Оценка плана документирования.

Приложение Н. Образец спецификации стиля.

Стандарт IEEE 1063-1987 (подтвержден 1993) отражает общие требования к пользовательской документации на программные средства широкого применения. Стандарт определяет минимальные требования к структуре и содержанию комплекта документов для пользователей программных продуктов. Стандарт ориентирован на документы, применяемые при инсталляции, эксплуатации и поставке ПС любого размера и назначения, но без изменения и сопровождения программ. Он не применим для технологической документации, используемой при проектировании, разработке, тестировании, испытаниях и сопровождении ПС, а также для оформления коммерческих пакетов прикладных программ. Использование стандарта не должно препятствовать применению более строгих и широких требований к документам, а также собственных стандартов предприятия по стилю изложения документов.

Стандарт ISO 9127 рекомендуется для создания пользовательской документации на коммерческие пакеты (закрытые коробки) программных средств, поставляемых на рынок. Пользовательская и рекламная документация на пакеты программ должна включать:

Общие сведения: введение; ограничения; область применения; определения; ссылки.

Пользовательская документация – инструкция по эксплуатации должна содержать описание, в котором заключена вся информация, необходимая пользователю для установки, запуска и применения ПС. Обычно эта документация представляет собой одно или несколько руководств, заключенных вместе с носителями ПС внутри упаковки. В результате пользователи не могут ознакомиться с детальным руководством до тех пор, пока пакет не куплен. Состав пользовательской документации – раздел 1 стандарта представлен в п. 7.10. Описание целей и области применения публикуется на внешней упаковке пакета ПС. Его задачей является дать возможность будущему покупателю оценить применимость ПС к своим потребностям.

В Советском Союзе в 70-е годы была разработана Единая Система Программной Документации (ЕСПД) в составе группы стандартов ГОСТ 19.ХХХ. Большинство этих стандартов устарело, не соответствует современным требованиям и их применение не целесообразно. Более качественно стандартизация документирования программ и данных отражена в некоторых стандартах по автоматизированным системам ГОСТ 34.ХХХ, утвержденных в конце 80-х годов. В настоящее время наиболее полезно освоить и использовать некоторые их фрагменты, которые можно отнести к документированию программ и данных, из стандартов:

ГОСТ 34.201-89 – Информационная технология. Виды, комплектность и обозначение документов при создании автоматизированных систем;

ГОСТ 34.602-90 – Информационная технология. Техническое задание на создание автоматизированных систем;

РД 50-34.698-90 – Методические указания. Информационная технология. Автоматизированные системы. Требования к содержанию документов.