Единая система программной документации

Размещено на http://www.allbest.ru//

ВВЕДЕНИЕ

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

Стандарты ЕСПД определяют общие положения и основополагающие стандарты, правила

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

основополагающие и организационно-методические стандарты;

стандарты, определяющие формы и содержание программных документов, применяемых при обработке данных;

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



1.ОБЩАЯ ЧАСТЬ

1.1 Общие положения

Техническое задание оформляют на листах формата А4 и/или А3, как правило, без заполнения полей листа. Номера листов (страниц) проставляют в верхней части листа над текстом.

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

Техническое задание должно содержать следующие разделы:

наименование и область применения;

основание для разработки;

назначение разработки;

технические требования к программе или программному изделию;

технико-экономические показатели;

стадии и этапы разработки;

порядок контроля и приемки;

приложения.

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

Содержание разделов

В разделе Наименование и область применения указывают наименование, краткую характеристику области применения программы или программного изделия и объекта, в котором используют программу или программное изделие.

В разделе Основание для разработки должны быть указаны:

документ (документы), на основании которых ведется разработка;

организация, утвердившая этот документ, и дата его утверждения;

наименование и (или) условное обозначение темы разработки.

Применительно к специфике учебного процесса основанием может служить задание на курсовое проектирование, приказ по институту от __.__. за N ___., договор __.__. за N ___., и т.п.

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

Например: Программа представляет собой ядро автоматизированного рабочего места (АРМ) разработчика непрерывных линейных систем автоматического управления (САУ), позволяющее пользователю решать задачи анализа простых моделей.

Раздел Технические требования к программе или программному изделию должен содержать следующие подразделы:

требования к функциональным характеристикам;

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

условия эксплуатации;

требования к составу и параметрам технических средств;

требования к информационной и программной совместимости;

требования к маркировке и упаковке;

требования к транспортированию и хранению;

специальные требования.

Иными словами, здесь начинается конкретика. Описывается то, что должна делать программа и как она должна выглядеть.

Требования к функциональным характеристикам. Здесь должны быть указаны требования к составу выполняемых функций, организации входных и выходных данных, временным характеристикам и т.п.

Например: Программа должна позволять … вычислять … строить… создавать …

Исходные данные : текстовый файл с заданной …

Выходные данные : графическая и текстовая информация - результаты анализа системы…; текстовые файлы - отчеты о … диагностика состояния системы и сообщения о всех возникших ошибках.

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

Здесь "выгадать" что-то сложно. В лучшем случае может пройти вариант, при котором ваша программа работает только с абсолютно корректными данными. Обычно Заказчик на это не идет, но попробовать можно.

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

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

С этим пунктом сложностей обычно не возникает. К сожалению, пункт о профессиональности пользователя Заказчиком подразумевается обязательно. Это, конечно, лишний повод придраться к вашей программе. Впрочем, здесь можно ограничиться фразами вида "Условия эксплуатации программы совпадают с условиями эксплуатации ПЭВМ IBM PC и совместимых с ними ПК", "Программа должная быть рассчитана на непрофессионального пользователя." и т.п.

Требования к составу и параметрам технических средств. Указывают необходимый состав технических средств с указанием их технических характеристик.

Здесь главное - ничего не забыть и все предусмотреть, с одной стороны (а то подсунут какой-нибудь IBM PC/XT с монохромным дисплеем и без мыши), а с другой - не переборщить с повышенными требованиями, иначе Заказчик найдет более покладистого Исполнителя.

Например: Необходимо наличие IBM PC - совместимого ПК с графическим адаптером EGA (VGA). Необходимое дисковое пространство - не менее 600 Кб, объем свободной оперативной памяти - не менее 400 Кб. Желательно наличие драйвера EMS и манипулятора типа "мышь".

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

Например: Программа должна работать автономно под управлением ОС MS DOS версии не ниже Базовый язык программирования - Turbo Pascal 6.0.

Требования к маркировке и упаковке и требования к транспортированию и хранению являются достаточно экзотическими. В общем случае здесь указывают требования к маркировке программного изделия, варианты и способы упаковки. А в требованиях к транспортированию и хранению должны быть указаны для программного изделия условия транспортирования, места хранения, условия хранения, условия складирования, сроки хранения в различных условиях.

Специальные требования - это весьма ответственная вещь. Их лучше, по возможности, всячески избегать. И заявить об этом сразу.

Например: Специальных требований к временным характеристикам программы не предъявляется. Специальных требований к емкостным характеристикам программы не предъявляется.

Технико-экономические показатели. Этот самый сложный для программиста пункт есть далеко не всегда. Он нужен прежде всего тогда, когда вашей целью является обоснование огромной эффективности и важности выполняемой работы. На Заказчика этот пункт действует, обычно, очень хорошо. По крайне мере, это лучшее обоснование сроков и денежных сумм разработки.

В этом разделе должны быть указаны: ориентировочная экономическая эффективность, предполагаемая годовая потребность (например: предполагаемое число обращений к комплексу в целом в год - 365 сеансов работы), экономические преимущества разработки по сравнению с лучшими отечественными и зарубежными образцами или аналогами.

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

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

Здесь описываются стандартные этапы. Главное - грамотно определиться со сроками. По возможности, старайтесь равномерно распределить этапы по срокам (и суммам). Помните, что не все проекты доживают до последней стадии. А отчеты должны быть по каждому этапу. Помните также, что больше всего времени займет рабочий проект. Если вы не успеете сделать в срок документацию, то Заказчик имеет полное право вообще не принять работу со всеми вытекающими последствиями.

Основными и непременными стадиями и этапами являются само техническое задание, эскизный проект, технический и рабочий проекты.

Эскизный проект. На этой стадии детально разрабатываются структуры входных и выходных данных, определяется форма их представления. Разрабатывается общее описание алгоритма, сам алгоритм, структура программы. Разрабатываются план мероприятий по разработке и внедрению программы.

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

Рабочий проект. На этой стадии осуществляется программирование и отладка программы, разработка программных документов, программы и методики испытаний. Подготавливаются контрольно-отладочные примеры. Окончательно оформляются документация и графический материал. Обычно указывается, что в ходе разработки программы должна быть подготовлена следующая документация:

текст программы;

описание программы;

программа и методика испытаний;

описание применения;

руководство пользователя.

Это - стандартные требования. Если Заказчик соглашается с тем, что можно представить не весь этот список, то это означает несерьезность его намерений в отношении вас и вашего продукта.

Графического материала может и не быть. Особенно тогда, когда вы не собираетесь докладывать о результатах своей работы. Но для серьезных проектов этот пункт обязателен.

Например: В ходе разработки программы должен быть подготовлен следующий графический материал:

технико-экономические показатели;

структура программы;

формат представления входных данных программы;

общая схема алгоритма (2 листа);

основные вычислительные алгоритмы;

пример работы программы.

В разделе Порядок контроля и приемки должны быть указаны виды испытаний и общие требования к приемке работы. Если возможно, то в этом пункте укажите, что "контроль и приемка разработки осуществляются на предоставляемой Заказчиком технике", иначе вас могут обязать принести технику с собой.

Например: Контроль и приемка разработки осуществляются на основе испытаний контрольно-отладочных примеров. При этом проверяется выполнение всех функций программы.

В Приложениях к техническому заданию, при необходимости, приводят:

перечень научно-исследовательских и других работ, обосновывающих разработку;

схемы алгоритмов, таблицы, описания, обоснования, расчеты и другие документы, которые могут быть использованы при разработке;

другие источники разработки.



2. СПЕЦ. ЧАСТЬ

2.1 Стадии разработки (ГОСТ 19.102-77)

Этот стандарт устанавливает стадии разработки программ, программной документации, а также этапы и содержание работ:

Стадии разработки	Этапы работ	Содержание работ
Техническое задание	Обоснование необходимости разработки программы	Постановка задачи. Сбор исходных материалов. Выбор и обоснование критериев эффективности и качества разрабатываемой программы. Обоснование необходимости проведения научно-исследовательских работ.
	Научно-исследователь-ские работы	Определение структуры входных и выходных данных. Предварительный выбор методов решения задач. Обоснование целесообразности применения ранее разработанных программ. Определение требований к техническим средствам. Обоснование принципиальной возможности решения поставленной задачи.
	Разработка и утверждение технического задания	Определение требований к программе. Разработка технико-экономического обоснования разработки программы. Определение стадий, этапов и сроков разработки программы и документации на нее. Выбор языков программирования. Определение необходимости проведения научно-исследовательских работ на последующих стадиях. Согласование и утверждение технического задания.
Эскизный проект	Разработка эскизного проекта	Предварительная разработка структуры входных и выходных данных. Уточнение методов решения задачи. Разработка общего описания алгоритма решения задачи. Разработка технико-экономического обоснования.
	Утверждение эскизного проекта	Разработка пояснительной записки. Согласование и утверждение эскизного проекта
Технический проект	Разработка технического проекта	Уточнение структуры входных и выходных данных. Разработка алгоритма решения задачи. Определение формы представления входных и выходных данных. Определение семантики и синтаксиса языка. Разработка структуры программы. Окончательное определение конфигурации технических средств.
	Утверждение технического проекта	Разработка плана мероприятий по разработке и внедрению программ. Разработка пояснительной записки. Согласование и утверждение технического проекта.
Рабочий проект	Разработка программы	Программирование и отладка программы
	Разработка программной документации	Разработка программных документов в соответствии с требованиями ГОСТ 19.101-77.
	Испытания программы	Разработка, согласование и утверждение программы и методики испытаний. Проведение предварительных государственных, межведомственных, приемо-сдаточных и других видов испытаний. Корректировка программы и программной документации по результатам испытаний.
Внедрение	Подготовка и передача программы	Подготовка и передача программы и программной документации для сопровождения и (или) изготовления. Оформление и утверждение акта о передаче программы на сопровождение и (или) изготовление. Передача программы в фонд алгоритмов и программ.

Примечания:

Допускается исключать вторую стадию разработки, а в технически обоснованных случаях -- вторую и третью стадии. Необходимость проведения этих стадий указывается в техническом задании.

Допускается объединять, исключать этапы работ и (или) их содержание, а также вводить другие этапы работ по согласованию с заказчиком.

2.2 Описание программы (ГОСТ 19.402-78)

Этот стандарт ориентирован на документирование результирующего продукта разработки.

Строго говоря, существуют два разных документа, имеющих, правда, много общего. Это ОБЩЕЕ ОПИСАНИЕ (ГОСТ 19.502-78) и ОПИСАНИЕ ПРОГРАММЫ (ГОСТ 19.402-78). Однако, в силу того, что реально создать качественно и тот, и другой, не прибегая к почти полному дублированию, выдирая куски, весьма сложно, было бы достаточно реализовать один, более общий, "гибридный" документ. Назовем его "Описанием программы".

На самом деле "Описание программы" в своей содержательной части может дополняться разделами и пунктами, взятыми и из стандартов для других описательных документов и руководств: ГОСТ 19.404-79 ЕСПД. Пояснительная записка, ГОСТ 19.503-79 ЕСПД. Руководство системного программиста, ГОСТ 19.504-79 ЕСПД. Руководство программиста, ГОСТ 19.505-79 ЕСПД. Руководство оператора и т.п. В частности, из Пояснительной записки можно взять схему алгоритма, общее описание алгоритма и (или) функционирования программы, а также обоснование принятых технических и технико-экономических решений.

Описание программы обязательно должно включать информационную часть - аннотацию и содержание.

Основная часть документа должна состоять из вводной части и следующих разделов:

функциональное назначение;

описание логики.

условия применения;

состав и функции.

В зависимости от особенностей программы допускается введение дополнительных разделов.

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

Например: Программа "Автоматизированное рабочее место разработчика САУ" предназначена для … реализована на …. Программа поддерживает …

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

Например: Программа предназначена для решения задач … Программа представляет собой ядро автоматизированного рабочего места …

Пользователь имеет возможность …, осуществить …, запустить …, проанализировать …, получить результаты анализа и обработки …, построить … и т.п.

В разделе "Описание логики" указывают:

описание структуры программы и ее основных частей

(например: В состав программы входит следующее:

пользовательский интерфейс,

модуль определения путей в графе,

модуль расчета передаточной функции,

модуль построения амплитудно- и фазочастотных характеристик,

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

текстовый редактор).

описание функций составных частей и связей между ними;

Например: Программа состоит из шести модулей: интерфейсный модуль; модуль определения …; модуль расчета …; модуль …и т.п..

Интерфейсный модуль построен на двух типах диалогов: диалог "вопрос - ответ" и диалог типа "меню". Интерфейсный модуль управляет …

Модуль определения … Он является …

Модуль расчета …и т.д.

сведения о языке программирования;

Например: Программа написана на языке …с использованием компилятора …

описание входных и выходных данных для каждой из составных частей;

Например: ВХОДНЫЕ ДАННЫЕ. Входными данными для программы является текстовый файл, описывающий расширенную матрицу инциденций графа исследуемой системы.

ВЫХОДНЫЕ ДАННЫЕ. Выходными данными являются:

выводимая на экран графическая и текстовая информация (результаты анализа системы);

файлы в одном из графических форматов - копии изображения построенных характеристик (АЧХ,ФЧХ и т.д.);

текстовые файлы - отчеты о проведенных исследованиях;

диагностика состояния системы и сообщения о всех возникших ошибках.

описание логики составных частей (при необходимости следует составлять описание схем программ).

При описании логики программы необходима привязка к тексту программы.

В разделе Состав и функции указывают описание состава и функции программ, применяемых методов решения задач.

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

Например: Программа эксплуатируется на персональном компьютере (ПК) типа IBM PC/AT. Для работы в диалоговом режиме используется экран дисплея, клавиатура и манипулятор типа "мышь". Для поддержки графического режима необходим адаптер EGA (VGA). Входные данные хранятся на флоппи- и/или жестком дисках. Программа работает под управлением ОС …

В приложение к описанию могут быть включены справочные материалы (иллюстрации, таблицы, графики, примеры и т.п.)

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

Вызова и загрузки системы

Например: Загрузка программы осуществляется набором в командной строке DOS имени загрузочного модуля - SBM80N.EXE с возможным указанием имени файла данных.

2.3 Текст программы (ГОСТ 19.401-78)

Требования к оформлению текста программы достаточно просты и естественны для грамотного программиста. Основное, чем требуется руководствоваться при создании этого документа - это то, что текст программы должен быть удобочитаемым.

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

Основная часть документа должна состоять из текстов одного или нескольких разделов, которым даны наименования.

Текст каждого программного файла начинается с "шапки", в которой указывается:

наименование программы,

автор,

дата создания программы,

номер версии,

дата последней модификации.

Обязательными являются комментарии, а также строгое соблюдение правил отступа. Помните, оправдать можно даже неумение создавать программную документацию. А некрасивый текст программы - никогда. Ссылки на то, что этот текст понятен самому автору всерьез не воспринимаются. Тексты программ должно быть не стыдно давать читать другим людям.

Ниже приведен пример подобного хорошо читаемого текста программы (взят с сайта Николая Гехта, e-mail:geht@omskreg.ru, http://users.omskreg.ru/~geht)

/* Исходные тексты Windows'98

Автор: Nobody Really

Source Code to Windows 98

*/

#include "win31.h"

#include "win95.h"

#include "evenmore.h"

#include "oldstuff.h"

#include "billrulz.h"

#include "monopoly.h"

#define INSTALL = HARD

char make_prog_look_big[1600000];

void main()

{

while(!CRASHED)

{

display_copyright_message();

display_bill_rules_message();

do_nothing_loop();

if(first_time_installation)

{

make_50_megabyte_swapfile();

do_nothing_loop();

totally_screw_up_HPFS_file_system();

search_and_destroy_the_rest_of_OS/2();

disable_Netscape();

disable_RealPlayer();

disable_Corel_Products();

hang_system();

}

write_something(anything);

display_copyright_message();

do_nothing_loop();

do_some_stuff();

if(still_not_crashed)

{

display_copyright_message();

do_nothing_loop();

basically_run_windows_3.1();

do_nothing_loop();

do_nothing_loop();

}

}

if(detect_cache())

disable_cache();

if(fast_cpu())

{

set_wait_states(lots);

set_mouse(speed, very_slow);

set_mouse(action, jumpy);

set_mouse(reaction, sometimes);

}

/* printf("Welcome to Windows 3.11"); */

/* printf("Welcome to Windows 95"); */

printf("Welcome to Windows 98");

if(system_ok())

crash(to_dos_prompt)

else

system_memory = open("a:\swp0001.swp", O_CREATE);

while(something)

{

sleep(5);

get_user_input();

sleep(5);

act_on_user_input();

sleep(5);

}

create_general_protection_fault();

}

2.4 Программа и методика испытаний (ГОСТ 19.301-79)

В этом документе содержится описание того, что и как необходимо сделать, дабы убедиться (и убедить Заказчика) в правильности работы программы. Фактически, этот документ является определяющим для приемо-сдаточных испытаний. Грамотно составленная программа и методика испытаний - это залог подписания акта сдачи-приемки, т.е. того, во имя чего вы потратили столько сил и времени.

Формально этот ГОСТ используется для разработки документов планирования и проведения испытательных работ по оценке готовности и качества программной системы. Документ содержит описание объекта и цели испытаний, требования к программе и к программной документации, средства и порядок испытаний, а также описание тестовых примеров.

Составные части этого документа проще и нагляднее описывать сразу в виде примеров.

Объект испытаний

Пример: Объектом испытаний является программа …, предназначенная для …

Цель испытаний

Пример: Проверка надежности функционирования программы.

Требования к программе

Пример: Функционирование программы не должно приводить к сбою (фатальному нарушению работы системы). Организация диалога должна предусматривать защиту от ввода некорректных данных. Программа должна выдавать диагностику состояния системы и сообщения о любых возникших ошибках … и т.п.

Требования к программной документации

Пример: Состав программной документации, предъявляемой на испытании:

описание программы (ГОСТ 19.402-78);

программа и методика испытаний (ГОСТ 19.301-79);

текст программы (ГОСТ 19.401-78).

Средства и порядок испытаний

Пример: Программа работает в соответствии с условиями эксплуатации ОС MS DOS (версия не ниже 3.0) на ПК типа IBM PC/AT, а также на совместимых с ним. Для работы необходим также адаптер EGA (VGA).

Порядок проведения испытаний:

Запуск программы осуществляется ….

Выбирается …

Нажимается …

Последовательно выбираются …

Тестовые примеры

Пример: Для проведения испытаний предлагаются …, описание которых содержатся в файлах …Содержимое тестовых файлов и результаты работы программы приведены в Приложении 1.

И, наконец, рассмотрим последний стандарт ЕСПД, который называется

2.5 Требования к программным документам, выполненным печатным способом (ГОСТ 19.106-78)

Этот стандарт устанавливает правила выполнения программных документов для вычислительных машин, комплексов и систем независимо от их назначения и области применения и предусмотренных стандартами ЕСПД.

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

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

Повреждение листов документов, помарки и следы не полностью удаленного текста (графики) не допускаются.

Программные документы оформляют на листах формата А4. Кроме того:

допустимо оформление на листах формата А3;

при машинном способе выполнения документа допускаются отклонения размеров листов, соответствующих форматам А4 и А3, определяемые возможностями применяемых технических средств; на листах форматов А4 и А3, предусматриваемых выходными характеристиками устройств вывода данных, при изготовлении документа машинным способом;

при изготовлении документа типографским способом возможно использование листов типографических форматов.

Расположение материалов программного документа осуществляется в следующей последовательности:

титульная часть:

лист утверждения (не входит в общее количество листов документа);

титульный лист (первый лист документа);

информационная часть:

аннотация;

лист содержания;

основная часть:

текст документа (с рисунками, таблицами и т.п.);

перечень терминов и их определений;

перечень сокращений;

приложения;

предметный указатель;

перечень ссылочных документов;

часть регистрации изменений:

лист регистрации изменений.

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

Допускается включение в документ частей текста программы, оформляемых в соответствии с правилами языка, на котором написан текст программы.

Аннотацию размещают на отдельной странице (страницах), снабжают заголовком "АННОТАЦИЯ", нумеруют и включают в содержание документа.

Содержание документа размещают на отдельной странице (страницах), снабжают заголовком "СОДЕРЖАНИЕ" и включают в общее количество страниц документа. В содержании документа дается перечисление наименований разделов и подразделов и номеров страниц.

Текст каждого документа, при необходимости, разбивается на пункты, а пункты - на подпункты, независимо от того, разделен документ на части, разделы и подразделы или нет.

Заголовки разделов пишут прописными буквами и размещают симметрично относительно правой и левой границ текста. Заголовки подразделов записывают с абзаца строчными буквами (кроме первой прописной). Переносы слов в заголовках не допускаются. Точку в конце заголовка не ставят. Каждый раздел рекомендуется начинать с нового листа.

Разделы, подразделы, пункты и подпункты следует нумеровать арабскими цифрами с точкой. Разделы должны иметь порядковый номер (1, 2 и т.д.)

Текст документа. Текст документа должен быть кратким, четким, исключающим возможность неверного толкования. Термины и определения должны быть едиными и соответствовать установленным стандартам, а при их отсутствии - общепринятым в научно-технической литературе, и приводиться в перечне терминов.

Необходимые пояснения к тексту документа могут оформляться сносками. Сноска обозначается цифрой со скобкой, вынесенной на уровень линии верхнего обреза шрифта.

Если сноска относится к отдельному слову, знак сноски помещается непосредственно возле этого слова, если же к предложению целом, то в конце предложения. Текст сноски располагают в конце страницы и отделяют от основного текста линией длиной 3 см, проведенной в левой части страницы.

Иллюстрации. Иллюстрации могут быть расположены в тексте документа и (или) в приложениях. Иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа.

В приложениях иллюстрации нумеруются в пределах каждого приложения в порядке, установленном для основного текста документа. Ссылки на иллюстрации дают по типу: "рис.12" или "(рис.12)". Иллюстрации могут иметь тематический заголовок и подрисуночный текст, поясняющий содержание иллюстрации.

Формулы. Формулы в документе, если их более одной, нумеруются арабскими цифрами, номер ставят с правой стороны страницы, в скобках на уровне формулы. В пределах всего документа или его частей, в случае деления документа на части, формулы имеют сквозную нумерацию.

Ссылки в тексте на порядковый номер формулы дают в скобках, например: "в формуле (3)". При делении документа на части номер части ставится перед порядковым номером формулы и отделяется от последней точкой, например: "в формуле (1.4)".

Значение символов, входящих в формулу, должны быть приведены непосредственно под формулой. Значение каждого символа печатают с новой строки в той последовательности, в какой они приведены в формуле. Первая строка расшифровки должна начинаться со слова "где", без двоеточия после него.

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

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

Примечания. В примечаниях к тексту и таблицам указывают только справочные и пояснительные данные. Одно примечание не нумеруется. После слова "Примечание" ставят точку. Несколько примечаний следует нумеровать по порядку арабскими цифрами с точкой. После слова "Примечание" ставят двоеточие. Текст примечаний допускается печатать только через один интервал.

Сокращения. Сокращения слов в тексте и надписях под иллюстрациями не допускаются, за исключением:

сокращений, установленных в ГОСТ 2.316-68, и общепринятых в русском языке;

сокращений, применяемых для обозначения программ, их частей и режимов работы, в языках управления заданиями, в средствах настройки программы и т.п., обозначаемых буквами латинского алфавита.

Приложения. Иллюстрированный материал, таблицы или текст вспомогательного характера допускается оформлять в виде приложений. Приложения оформляют как продолжение данного документа на последующих страницах или выпускают в виде отдельного документа.

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

Приложение 1, Приложение 2 и т.д.

При выпуске приложения отдельным документом, на титульном листе под наименованием документа следует указывать слово "Приложение", а при наличии нескольких приложений указывают также его порядковый номер.



3. СТАНДАРТИЗАЦИЯ В ОБЛАСТИ ДОКУМЕНТИРОВАНИЯ ПРОГРАММНЫХ СРЕДСТВ

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

Итак, ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на процессы жизненного цикла ПС.

Тем не менее, до пересмотра всего комплекса, многие стандарты могут с пользой применяться в практике документирования ПС. Эта позиция основана на следующем:

n стандарты ЕСПД вносят элемент упорядочения в процесс документирования ПС; n предусмотренный стандартами ЕСПД состав программных документов вовсе не такой «жесткий», как некоторым кажется: стандарты позволяют вносить в комплект документации на ПС дополнительные виды программных документов (ПД), необходимых в конкретных проектах, и исключать многие ПД; n стандарты ЕСПД позволяют вдобавок мобильно изменять структуры и содержание установленных видов ПД исходя из требований заказчика и пользователя.

При этом стиль применения стандартов может соответствовать современному общему стилю адаптации стандартов к специфике проекта: заказчик и руководитель проекта выбирают уместное в проекте подмножество стандартов и ПД, дополняют выбранные ПД нужными разделами и исключают ненужные, привязывают создание этих документов к той схеме ЖЦ, которая используется в проекте.

Надо сказать, что наряду с комплексом ЕСПД официальная нормативная база РФ в области документирования ПС и в смежных областях включает ряд перспективных стандартов (отечественного, межгосударственного и международного уровней), о составе

и содержании которых далее будет сказано.

Государственные стандарты РФ (ГОСТ Р)

В РФ действует ряд стандартов в части документирования ПС, разработанных на основе прямого применения международных стандартов ИСО. Это -- самые «свежие» по времени принятия стандарты. Некоторые из них впрямую адресованы руководителям проекта или директорам информационных служб. Вместе с тем они неоправданно мало известны в среде профессионалов. Вот их представление.

ГОСТ Р ИСО/МЭК 9294-93 Информационная технология. Руководство по управлению документированием программного обеспечения. Стандарт полностью соответствует международному стандарту ИСО/МЭК ТО 9294:1990 и устанавливает рекомендации по эффективному управлению документированием ПС для руководителей, отвечающих за их создание..

Подготовка документации на программные средства в соответствии с имеющимися ГОСТами ГОСТ Р ИСО/МЭК 9126-93 Информационная технология. Оценка программной продукции. Характеристики качества и руководства по их применению. Стандарт полностью соответствует международному стандарту ИСО/МЭК 9126:1991. В его контексте под характеристикой качества понимается «набор свойств (атрибутов) программной продукции, по которым ее качество описывается и оценивается». Стандарт определяет шесть комплексных характеристик, которые с минимальным дублированием описывают качество ПС (ПО, программной продукции): функциональные возможности;

надежность; практичность; эффективность; сопровождаемость; мобильность.

ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов. Стандарт полностью соответствует международному стандарту ИСО 9127:1989. В контексте настоящего стандарта под потребительским программным пакетом (ПП) понимается «программная продукция, спроектированная и продаваемая для выполнения определенных функций;

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

ГОСТ Р ИСО/МЭК 8631-94 Информационная технология.

Практики используют еще один путь: сами переводят и используют в своих проектах современные стандарты на организацию ЖЦ ПС и их документирование. Но этот путь страдает как минимум тем недостатком, что разные переводы и адаптации стандартов, сделанные разными разработчиками и заказчиками, будут отличаться массой деталей. Эти

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

Подготовка документации на программные средства (ПС) в соответствии с имеющимися ГОСТами



6. ПОДГОТОВКА ДОКУМЕНТАЦИИ НА ПРОГРАММНЫЕ СРЕДСТВА В СООТВЕТСТВИИ С ИМЕЮЩИМИСЯ ГОСТАМИ

Итак, ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на

процессы жизненного цикла ПС об этом стандарте далее будет сказано подробнее).

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

Международный стандарт ISO/IEC 12207: 1995-08-01 на организацию ЖЦ продуктов программного обеспечения (ПО) -- казалось бы весьма неконкретный, но вполне новый и отчасти "модный" стандарт.

Стандарты комплекса ГОСТ 34 на создание и развитие автоматизированных систем (АС) -- обобщенные, но воспринимаемые как весьма жесткие по структуре ЖЦ и проектной документации. Но эти стандарты многими считаются бюрократическими до вредности и консервативными до устарелости. Насколько это так, а насколько ГОСТ 34 остается работающим с пользой -- полезно разобраться.

В своей статье Е.З.Зиндер подробно останавливается на методике Oracle CDM (Custom Development Method) по разработке прикладных информационных систем под заказ --конкретный материал, детализированный до уровня заготовок проектных документов, рассчитанных на прямое использование в проектах АС с опорой на инструментарий Oracle.

Виды программных документов, разрабатываемых на разных стадиях и их коды

Стадии разработки

Код вида Рабочий проект

документа Вид документа Эскизный проект

Технический проект

Компонент комплекс

-- Спецификация -- -- ! +

05 Ведомость держателей

подлинников -- -- -- ?

12 Текст программы -- -- + ?

13 Описание программы -- -- ? ?

20 Ведомость эксплуатационных

документов -- -- ? ?

30 Формуляр -- -- ? ?

31 Описание применения -- -- ? ?

32 Руководство системного

программиста -- -- ? ?

33 Руководство программиста -- -- ? ?

34 Руководство оператора -- -- ? ?

35 Описание языка -- -- ? ?

46 Руководство по техническому

обслуживанию -- -- ? ?

51 Программа и методика

испытаний -- -- ? ?

81 Пояснительная записка ? ? -- --

90-99 Прочие документы ? ? ? ?

Условные обозначения:

+ документ обязательный;

! документ обязательный для компонентов, имеющих самостоятельное применение;

? необходимость составления документа определяется на этапе разработки и утверждения технического задания;

-- документ не составляют.

Допускается объединять отдельные виды эксплуатационных документов (за исключением

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

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

Наряду с ЕСПД на межгосударственном уровне действуют еще два стандарта, также относящихся к документированию ПС и принятых не так давно, как большая часть ГОСТ



7 ОБЩАЯ ХАРАКТЕРИСТИКА СОСТОЯНИЯ

7.1 Государственные стандарты РФ (ГОСТ Р)

В РФ действует ряд стандартов в части документирования ПС, разработанных на основе

прямого применения международных стандартов ИСО. Это -- самые "свежие" по времени принятия стандарты. Некоторые из них впрямую адресованы руководителям проекта или директорам информационных служб. Вместе с тем они неоправданно мало известны в среде профессионалов. Вот их представление.

ГОСТ Р ИСО/МЭК 9294-93 Информационная технология. Руководство по управлению документированием программного обеспечения. Стандарт полностью соответствует международному стандарту ИСО/МЭК ТО 9294:1990 и устанавливает рекомендации по эффективному управлению документированием ПС для руководителей, отвечающих за их создание. Целью стандарта является оказание помощи в определении стратегии

документирования ПС; выборе стандартов по документированию; выборе процедур документирования; определении необходимых ресурсов; составлении планов документирования.

ГОСТ Р ИСО/МЭК 9126-93 Информационная технология. Оценка программной продукции.

Характеристики качества и руководства по их применению. Стандарт полностью соответствует международному стандарту ИСО/МЭК 9126:1991. В его контексте под характеристикой качества понимается "набор свойств (атрибутов) программной продукции, по которым ее качество описывается и оценивается". Стандарт определяет шесть комплексных характеристик, которые с минимальным дублированием описывают качество ПС (ПО, программной продукции): функциональные возможности; надежность;

практичность; эффективность; сопровождаемость; мобильность. Эти характеристики образуют основу для дальнейшего уточнения и описания качества ПС.

ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов. Стандарт полностью соответствует международному стандарту ИСО 9127:1989. В контексте настоящего стандарта под потребительским программным пакетом (ПП) понимается "программная продукция, спроектированная и продаваемая для выполнения определенных функций; программа и соответствующая ей документация, упакованные для продажи как единое целое". Под документацией пользователя понимается документация, которая обеспечивает конечного пользователя информацией по установке и эксплуатации ПП. Под информацией на упаковке понимают информацию, воспроизводимую на внешней упаковке ПП.

7.2 МЕЖДУНАРОДНЫЙ СТАНДАРТ ISO/IEC 12207: 1995-08-01

Первая редакция ISO12207 подготовлена в 1995 году объединенным техническим комитетом ISO/IEC JTC1 "Информационные технологии, подкомитет SC7, проектирование программного обеспечения".

По определению, ISO12207 -- базовый стандарт процессов ЖЦ ПО, ориентированный на различные (любые!) виды ПО и типы проектов АС, куда ПО входит как часть. Стандарт определяет стратегию и общий порядок в создании и эксплуатации ПО, он охватывает ЖЦ ПО от концептуализации идей до завершения ЖЦ.

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

Каждый процесс ЖЦ разделен на набор действий, каждое действие -- на набор задач.

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

В стандарте ISO12207 описаны:

1. 5 основных процессов ЖЦ ПО:

? Процесс приобретения. Определяет действия предприятия-покупателя, которое приобретает АС, программный продукт или сервис ПО.

? Процесс поставки. Определяет действия предприятия-поставщика, которое снабжает покупателя системой, программным продуктом или сервисом ПО. программный документация стандартизация

? Процесс разработки. Определяет действия предприятия-разработчика, которое разрабатывает принцип построения программного изделия и программный продукт.

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

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

8 вспомогательных процессов, которые поддерживают реализацию другого процесса, будучи неотъемлемой частью всего ЖЦ программного изделия, и обеспечивают должное качество проекта ПО:

? решения проблем;

? документирования;

? управления конфигурацией;

? гарантирования качества, который использует результаты остальных

процессов группы обеспечения качества, в которую входят:

? Процесс верификации;

? Процесс аттестации;

? Процесс совместной оценки;

? Процесс аудита.__

Размещено на Allbest.ru

...