Стандарты документирования программных средств

1. Стандарты документирования программных средств 3.1. Введение 3.2. Общая характеристика состояния в области документирования программных средств. 3.3. Единая система программной документации. 3.4. Государственные стандарты Российской Федерации (ГОСТ Р)

2. 3.1. Введение Вопросы, возникающие при создании документации на ПС: • Что должно быть сделано, кроме собственно программы? • Что и как должно быть оформлено в виде документации? • Что передавать пользователям, а что — службе сопровождения? • Как управлять всем этим процессом? • Что должно входить в само задание на программирование?

3. 3.2. Общая характеристика состояния в области документирования программных средств. В состав ЕСПД входят: • основополагающие и организационно-методические стандарты; • стандарты, определяющие формы и содержание программных документов, применяемых при обработке данных; • стандарты, обеспечивающие автоматизацию разработки программных документов. К числу основных недостатков ЕСПД можно отнести: • ориентацию на единственную «каскадную» модель жизненного цикла ПС; • отсутствие четких рекомендаций по документированию характеристик качества ПС; • отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например ЕСКД; • нечетко выраженный подход к документированию ПС как товарной продукции; • отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю (хелпов); • отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов. • К числу основных достоинств ЕСПД можно отнести: • стандарты ЕСПД вносят элемент упорядочения в процесс документирования ПС; • • предусмотренный стандартами ЕСПД состав программных документов вовсе не такой «жесткий», как некоторым кажется: стандарты позволяют вносить в комплект документации на ПС дополнительные виды программных документов (ПД), необходимых в конкретных проектах, и исключать многие ПД; • • стандарты ЕСПД позволяют вдобавок мобильно изменять структуры и содержание установленных видов ПД исходя из требований заказчика и пользователя. Единая система программной документации — это комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, оформления и обращения программ и программной документации. Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей части, с документированием функциональных характеристик ПС. Следует отметить, что стандарты ЕСПД (ГОСТ 19) носят рекомендательный характер.

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

5. 3.4. Государственные стандарты Российской Федерации (ГОСТ Р) • ГОСТ Р ИСО/МЭК 9294-93. Информационная технология. Руководство по у правлению документированием программного обеспечения. • ГОСТ Р ИСО/МЭК 9126-93. Информационная технология. Оценка программной продукции. Характеристики качества и руководства по их применению. • ГОСТ Р ИСО 9127-94. Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов. • ГОСТ Р ИСО/МЭК 8631-94. Информационная технология. Программные конструктивы и условные обозначения для их представления. • ГОСТ Р ИСО/МЭК 12119:1994. Информационная технология. Пакеты программных средств. Требования к качеству и испытания.

6. ГОСТ Р ИСО/МЭК 12119:1994. Определяет требования: • к описанию продукта • к пользовательской документации • к программам и данным Исходные требования к продукту: • каждый пакет программ должен содержать описание продукта и документацию пользователя; • описание продукта должно содержать конкретную информацию, а все приводимые в нем формулировки должны быть проверяемыми (контролируемыми) и корректными; • требования к документации пользователя; • требования к любым программам и данным, входящим в состав пакета программ.

7. ГОСТ Р ИСО/МЭК 12119:1994 – описание продукта. 4. Надежность При необходимости в описание продукта должна быть вклю­чена информация по средствам предотвращения случайного или преднамеренного несанкционированного доступа к программам и данным. Описывая надежность продукта, необходимо провести ин­формацию по процедурам сохранение данных. Здесь также могут быть описаны дополнительные характеристики продукта, кото­рые обеспечивают его функциональные возможности, например: • проверки достоверности исходных данных; • защиту против серьезных последствий ошибки пользователя; • восстановление при ошибках. 2. Обозначения и указания (продолжение) 5. Должна быть определена система (технические и программные средства и их конфигурация), необходимая для ввода продукта в эксплуатацию, включая наименования изготовителей и обозначения типов всех ее частей, например: • процессоры, включая сопроцессоры; • объем основной (оперативной) памяти; • типы и объемы (памяти) периферийных запоминающих устройств; • расширяющие платы; • оборудование ввода и вывода; • сетевое оборудование; • системные и прочие программные средства. 6. Должны быть определены соответствующие интерфейсы или продукты, если в описании продукта имеются ссылки на интерфейсы с другими продуктами. Материал, подлежащий описанию: 1. Общие требования к содержанию. 2. Обозначения и указания. 3. Функциональные возможности. 4. Надежность. 5. Практичность. 6. Эффективность. 7. Сопровождаемость и мобильность. 2. Обозначения и указания (продолжение) 7. Должен быть определен каждый физический компонент поставляемого продукта, в частности, все печатные документы и все носители данных. 8. Должен быть установлен вид поставляемых программ, например исходные программы, объектные (рабочие) модули или загрузочные модули. 9. Должно быть указано, будет ли инсталляция продукта проводиться пользователем или нет. 10. Должно быть указано, будет или не будет предлагаться поддержка при эксплуатации продукта. 11. Должно быть указано, будет или не будет предлагаться сопровождение продукта. Если сопровождение предусматривается, то должно быть установлено, что оно подразумевает. 3. Обзор функций. В описании продукта должен быть приведен обзор функций продукта, вызываемых пользователем, необходимых для них данных и предоставляемых средств. Для каждой функции (особенно для ее опции или варианта) должно быть четко установлено, яв­ляется ли она частью: • продукта; • расширения продукта, полностью приведенного в описании продукта; • расширения продукта, на которое дана ссылка в описании продукта; • негарантируемого (необязательного) приложения. 2. Обозначения и указания 1. При обозначении одного или нескольких продуктов в рамках одного пакета необходимо хотя бы включать наименование продукта и обозначение его версии или даты выпуска. 2. Должны быть включены наименование и адрес поставщика. 3. Должны быть определены целевые рабочие задачи, которые могут быть выполнены данным продуктом. 4. Из описания продукта могут быть даны ссылки на нормативные документы, которым удовлетворяет данный продукт, в этом случае должны быть указаны соответствующие редакции данных документов. Граничные значения. Если использование продукта ограничено конкретными гра­ничными значениями для продукта, они должны быть указаны в описании продукта. Например: • минимальные или максимальные значения; • длины ключей; • максимальное число записей в файле; • максимальное число критериев поиска; • минимальный объем выборки. 5. Практичность 1. Интерфейс пользователя. 2. Требуемые знания. 3. Адаптация к потребностям пользователя. 4. Защита от нарушения авторских прав. 5. Эффективность применения и удовлетворение потребностей пользователя. 6. Эффективность Характер поведения продукта во времени, например время ответа и время оценки производительности для заданных функций при установленных условиях. 1. Общие требования к содержанию • быть достаточно понятным, полным и простым при изучении, чтобы обеспечить помощь потенциальным покупателям при оценке ими пригодности данного продукта для их нужд до его покупки; • быть внутренне непротиворечивым. Каждый термин должен иметь один и тот же смысл по всему документу; • формулировки должны быть проверяемыми и корректными. Описание продукта (product description); документ, определяющий свойства пакета программ, основным назначением которого является оказание помощи потенциальным покупателям в оценке пригодности для них данного продукта до его приобретения. Основным назначением описания продукта является помощь пользователю и потенциальному покупателю при оценке ими пригодности продукта для их нужд.

8. ГОСТ Р ИСО/МЭК 12119:1994 – документация пользователя. Характеристики документации: 1. Полнота (completeness). 2. Правильность (correctness). 3. Непротиворечивость (consistency). 4. Понятность (understandability). 5. Простотаобозрения (ease of overview). • 1. Полнота • Документация пользователя должна содержать информацию, необходимую для использования продукта: • Указание на все функции, установленные в описании продукта, и все вызываемые пользователем функции из программы. • Граничные значения, заданные в описании продукта, должны быть продублированы в документации пользователя. • Если установка (инсталляция) продукта может быть проведена пользователем, то в документацию пользователя должно быть включено руководство по установке продукта. • Если сопровождение продукта может проводиться пользователем, то в документацию пользователя должно быть включено руководство по сопровождению программы. 4. Понятность Документация пользователя должна быть понятной для сообщества пользователей, выполняющих указанную рабочую задачу, например, посредством использования в ней соответствующим образом подобранных терминов, графических вставок, уточняющих пояснений и путем ссылок на полезные источники информации. 3. Непротиворечивость Документы, входящие в комплект документации пользователя, не должны противоречить сами себе, друг другу и описанию продукта. Каждый термин должен иметь один и тот же смысл во всех документах. 5. Простота обозрения Документация пользователя должна быть достаточно проста для изучения пользователем, чтобы он мог выявить все описываемые в ней взаимосвязи компонентов продукта. В каждый документ могут быть включены оглавление и предметный указатель. 2. Правильность Вся информация в документации пользователя должна быть правильной. Кроме того, представление данной информации не должно содержать неоднозначных толкований и ошибок. Документация пользователя (user documentation) полный комплект документов, поставляемых в печатном или другом виде, который обеспечивает применение продукта, а также является его неотъемлемой частью.

9. ГОСТ Р ИСО/МЭК 12119:1994 – программы и данные. Простота использования. Исполнение функций, приводящих к серьезным последствиям при эксплуатации системы, должно быть обратимым или программы должны выдавать четкие предупреждения о последствиях выполнения данных функций и запрашивать разрешающее подтверждение перед выполнением соответствующей команды. В частности, к серьезным последствиям могут привести стирание или перезапись данных, а также прерывания режима продолжительной обработки. Если текст документа предоставляется в диалоговом режиме, то пользователю следует обеспечить возможность непосредственного доступа к отдельным структурным элементам текста, например, путем выбора данных элементов из отображенного на экране содержания документа или с помощью функции поиска по ключевым словам. Простота обозрения. На каждый носитель данных должно быть нанесено обозначение продукта, а если носителей несколько — различающий номер или текст. Пользователю, работающему с программами, всегда должна быть предоставлена возможность выяснения, какая из функций выполняется. Программы должны предоставлять пользователю информацию в таком виде, чтобы данная инфор-мация им легко воспринималась и читалась. Пользователь может руководствоваться соответствующими кодификаторами и классифи-каторами информации. Сообщения от программ следует проектировать таким образом, чтобы пользователь мог легко различать их типы. Форматы входных экранов, отчеты, а также другие исходные и выходные данные следует проектировать так, чтобы их можно было легко просматривать. Правильность. Программы и данные должны соответствовать всем обязатель­ным формулировкам, приведенным в описании продукта и доку­ментации пользователя. Функции должны выполняться методом, соответствующим рабочей задаче. В частности, программы и дан­ные должны удовлетворять всем требованиям из любого норма­тивного документа, на который дана ссылка в описании продукта. • Характеристики: • Функциональные возможности. • Установка • Реализация функций • Правильность • Непротиворечивость • 2. Надежность. • 3. Практичность. • Понятность • Простота обозрения • Простота использования • 4. Эффективность. • 5. Сопровождаемость. • 6. Мобильность. Непротиворечивость. Программы и данные не должны противоречить сами себе, а также описанию продукта и документации пользователя. Каж­дый термин везде должен иметь один и тот же смысл. Управление работой программы со стороны пользователя и соответствую­щая реакция программы (например, сообщения, выходные экран­ные форматы и печатные отчеты) должны быть единообразно структурированы. Надежность Система не должна приходить в такое состояние, чтобы пользователь не мог его контролировать, а данные не должны ни повреждаться, ни теряться. Это требование должно одинаково удовлетворяться в случаях, когда: • возможность реализуется при конкретных ограничениях; • имеют место попытки реализации возможности вне заданных ограничений; • неправильные исходные данные вводятся пользователем или от других программ, перечисленных в описании продукта; • нарушаются инструкции, заданные в документации пользователя. Программы должны обнаруживать нарушения синтаксических правил для исходных данных. Реализация функций. Все функции, указанные в документации пользователя, должны выполняться в виде, заданном в документации пользователя, на соответствующих средствах, с соответствующими характеристиками и данными, в рамках граничных значений, заданных там же. Установка (инсталляция). Если установка пакета может быть выполнена пользователем, то при ее проведении должна быть обеспечена возможность успешной установки программ в соответствии с информацией, содержащейся в руководстве по установке. Каждая из необходимых систем, указанных в описании продукта, должна быть пригодной для установки программ. В процессе установки должно быть определено, могут ли установленные программы функционировать, например, путем использования поставленных с программами контрольных примеров или самотестирования с выдачей соответствующих сообщений. Понятность. Запросы, сообщения и результаты выполнения программ должны быть понятными, например: • путем соответствующего выбора терминов; • путем графических представлений; • путем представления исходной информации; • путем пояснений из функции подсказки. В сообщениях об ошибках должна содержаться подробная информация, разъясняющая причину или способ исправления соответствующих ошибок из-за неправильного применения продукта (например, путем ссылки на элемент документации пользователя).