КУЛЬТУРА РАЗРАБОТКИ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ

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

• надежности;
• адекватной обработке нештатных ситуаций;
• легкой модернизируемости.

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

Общие этапы разработки программ :

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

Для определения требований к программе разработчику необходимо получить ответ на вопрос: «Насколько заказчик заинтересован в разработке программы?»

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

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

• Какова(-ы) цель(-ли) программы?
• Круг пользователей программы.
• Нормативная (правовая, справочная) база, на которую опираются процессы, алгоритмизируемые в программе.
• Возможность и необходимость дальнейшего развития программы.
• Контактное лицо, уполномоченное решать все вопросы от лица заказчика.
• Наличие материалов, которые есть или заказчик планирует подготовить для использования в программе (!!! Этот пункт особенно важен для разработки Web-сайтов).

Разработка технического задания в идеале должна осуществляться заказчиком. На практике зачастую это делает разработчик по причине отсутствия у заказчика квалифицированных специалистов, сведущих в области разработки программного обеспечения. Техническое задание, как правило, разрабатывается на основе ГОСТа 19.201-78 «ЕСПД. Техническое задание. Требования к содержанию и оформлению». В случаях разработки технического программного обеспечения в составе автоматизированных систем применяется ГОСТ 34.602-89 «Информационная технология. Техническое задание на создание автоматизированной системы».

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

На основе утвержденного технического задания разрабатывается проектная документация (проект ). Содержание проекта зависит от типа программного обеспечения и традиций предприятия разработчика.

Обязательными составляющими проекта должны быть:

• пояснительная записка (по ГОСТу 19.404-79 «ЕСПД. Пояснительная записка. Требования к содержанию и оформлению»).
• описание программы (по ГОСТу 19.402-78 «ЕСПД. Описание программы»).
• перечень терминов, используемых в проекте. Для web-сайтов в состав проекта включаются:
• эскиз дизайна сайта;
• перечень материалов, используемых в составе сайта;
• структура баз данных (в случае наличия таковых)

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

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

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

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

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

Тестирование программы производится следующим образом:

1. Определяется набор аппаратуры для производства тестирования.
2. Разрабатываются сценарии (контрольные примеры) для тестирования.
3. На основе сценариев проверяется работа программы в штатном режиме (проверяется правильность выполнения тех функций, которые программа и должна выполнять).
4. Проверяется работа программы в нештатных режимах (проверяется, устойчиво ли работает программа в режимах, которые могут возникать только при нарушении пользователями правил эксплуатации программы, например, ввод букв в цифровое поле).
5. Производится тестирование на удобство управления программой и качество интерфейсов.
6. Данные тестирования и его результаты обрабатываются и оформляются в соответствии с ГОСТом 34.603-92 «Информационная технология. Виды испытаний автоматизированных систем».
7. По мере выявления ошибок последние исправляются, и тестирование производится повторно.
8. После исправления всех ошибок программа передается в опытную эксплуатацию.

Заказчику на стадии опытной эксплуатации передается программа и обязательный пакет документации:

• ведомость эксплуатационных документов (по ГОСТу 19.507-79 «ЕСПД. Ведомость эксплуатационных документов»)
• формуляр (по ГОСТу 19.501-78 «ЕСПД. Формуляр. Требования к содержанию и оформлению»)
• описание применения (по ГОСТу 19.502-78 «ЕСПД. Описание применения. Требования к содержанию и оформлению»)
• руководство системного программиста (по ГОСТу 19.503-79 «ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению»)
• руководство оператора (по ГОСТу 19.505-79 «ЕСПД. Руководство оператора. Требования к содержанию и оформлению»).

В зависимости от вида задачи дополнительно могут передаваться:

• руководство программиста (по ГОСТу 19.504-79 «ЕСПД. Руководство программиста. Требования к содержанию и оформлению»)
• руководство по т/о (по ГОСТу 19.508-79 «ЕСПД. Руководство по техническому обслуживанию. Требования к содержанию и оформлению»).

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

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

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

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

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

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

На верх

ГОСТ 19.105-78* (Общие требования к программным документам)

Из данного ГОСТа мы получаем общие требования к оформлению программных документов. Ниже приведены наиболее важные разделы.

• Настоящий стандарт устанавливает общие требования к оформлению программных документов для вычислительных машин, комплексов и систем, независимо от их назначения и области применения и предусмотренных стандартами Единой системы программной документации (ЕСПД) для любого способа выполнения документов на различных носителях данных.
• Программный документ состоит из следующих условных частей:
• титульной;
• информационной;
• основной;
• регистрации изменений.
• Титульная часть состоит из листа утверждения и титульного листа. Правила оформления листа утверждения и титульного листа устанавливаются по ГОСТ 19.104-78.
• Информационная часть должна состоять из аннотации и содержания.
• Необходимость включения информационной части в различные виды программных документов установлена соответствующими стандартами ЕСПД на эти документы.
• В аннотации приводят сведения о назначении документа и краткое изложение его основной части.
• Содержание включает перечень записей о структурных элементах основной части документа, в каждую из которых входят:
• обозначение структурного элемента (номер раздела, подраздела и т.д.);
• наименование структурного элемента;
• адрес структурного элемента на носителе данных (например, номер страницы, номер файла и т.п.).
• Состав и структура основной части программного документа устанавливаются стандартами ЕСПД на соответствующие документы.
• Часть регистрации изменений (должна присуствовать в каждом программном документе)
• О каждом изменении программного документа в этой части делается запись в соответствии с требованиями ГОСТ 19.603-78.

На верх
==================================
ГОСТ 19.106-78* (Общие требования к программным документам, выполненным печатным
способом)
Из данного ГОСТа мы получаем общие правила для печатного способа выполнения программных документов . Ниже приведены наиболее важные разделы.

• Настоящий стандарт устанавливает правила выполнения программных документов для вычислительных машин, комплексов и систем независимо от их назначения и области применения и предусмотренных стандартами Единой системы программной документации (ЕСПД) для печатного способа выполнения.
• Стандарт не распространяется на программный документ «Текст программы».
• Состав и структура программного документа устанавливается по ГОСТ 19.105-78.
• Программный документ выполняют на одной стороне листа, через два интервала; допускается через один или полтора интервала.
• Программные документы оформляют:
• на листах формата А4 (ГОСТ 2.301-68) - при изготовлении документа машинописным или рукописным способом (форма 1). Допускается оформление на листах формата А3.

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

• Аннотацию размещают на отдельной (пронумерованной) странице с заголовком «АННОТАЦИЯ» и не нумеруют как раздел.
• В аннотации указывают издание программы, кратко излагают назначение и содержание документа. Если документ состоит из нескольких частей, в аннотации указывают общее количество частей.
• Содержание документа размещают на отдельной (пронумерованной) странице (страницах) после аннотации, снабжают заголовком «СОДЕРЖАНИЕ», не нумеруют как раздел и включают в общее количество страниц документа.
• Заголовки разделов пишут прописными буквами и размещают симметрично относительно правой и левой границ текста.
• Заголовки подразделов записывают с абзаца строчными буквами (кроме первой прописной).
• Переносы слов в заголовках не допускаются. Точку в конце заголовка не ставят.

• Расстояние между заголовком и последующим текстом, а также между заголовками раздела и подраздела должно быть равно:
• при выполнении документа машинописным способом - двум интервалам.
• Для разделов и подразделов, текст которых записывают на одной странице с текстом предыдущего раздела, расстояние между последней строкой текста и последующим заголовком должно быть равно:
• при выполнении документа машинописным способом - трём машинописным интервалам.
• Разделы, подразделы, пункты и подпункты следует нумеровать арабскими цифрами с точкой.
• В пределах раздела должна быть сквозная нумерация по всем подразделам, пунктам и подпунктам, входящим в данный раздел.
• Нумерация подразделов включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделённые точкой (2.1; 3.1 и т. д.).
• При наличии разделов и подразделов к номеру подраздела после точки добавляют порядковый номер пункта и подпункта (3.1.1, 3.1.1.1 и т.д.).

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

• Текст документа должен быть кратким, четким, исключающим возможность неверного толкования.
• Термины и определения должны быть едиными и соответствовать установленным стандартам, а при их отсутствии - общепринятым в научно-технической литературе, и приводиться в перечне терминов.
• Необходимые пояснения к тексту документа могут оформляться сносками.
• Сноска обозначается цифрой со скобкой, вынесенными на уровень линии верхнего обреза шрифта, например: «печатающее устройство 2) ...» или «бумага 5) ».
• Если сноска относится к отдельному слову, знак сноски помещается непосредственно у этого слова, если же к предложению целом, то в конце предложения. Текст сноски располагают в конце страницы и отделяют от основного текста линией длиной 3 см, проведённой в левой части страницы.
• Иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа.
• Формулы в документе, если их более одной, нумеруются арабскими цифрами, номер ставят с правой стороны страницы, в скобках на уровне формулы.
• Значение символов и числовых коэффициентов, входящих в формулу, должны быть приведены непосредственно под формулой. Значение каждого символа печатают с новой строки в той последовательности, в какой они приведены в формуле. Первая строка расшифровки должна начинаться со слова «где», без двоеточия после него.
• В программных документах допускаются ссылки на стандарты (кроме стандартов предприятий), технические условия и другие документы (например, документы органов Государственного надзора, правила и нормы Госстроя СССР). При ссылках на стандарты и технические условия указывают их обозначение.
• Ссылаться следует на документ в целом или на его разделы (с указанием обозначения и наименования документа, номера и наименования раздела или приложения). При повторных ссылках на раздел или приложение указывают только номер.
• В примечаниях к тексту и таблицам указывают только справочные и пояснительные данные.
• Одно примечание не нумеруется. После слова «Примечание» ставят точку.
• Несколько примечаний следует нумеровать по порядку арабскими цифрами с точкой. После слова «Примечание» ставят двоеточие.
• Сокращения слов в тексте и надписях под иллюстрациями не допускаются.
• Иллюстрированный материал, таблицы или текст вспомогательного характера допускается оформлять в виде приложений.
• Каждое приложение должно начинаться с новой страницы с указанием в правом верхнем углу слова «ПРИЛОЖЕНИЕ» и иметь тематический заголовок, который записывают симметрично тексту прописными буквами. (в итоге, для создания проекта, нам понадобится только лист регистрации изменений).
  
  • Настоящий стандарт устанавливает правила внесения изменений в программные документы, предусмотренные стандартами Единой системы программной документации (ЕСПД) и выполненные печатным способом.
  Из за значительного объема информации в данном ГОСТе и для экономии места на данной странице рекомендую самостоятельно просмотреть ГОСТ 19.604-78* . Готовый пример оформления "листа регистрации изменений" Вы можете просмотреть в любом программном документе, предоставленном в разделе СКАЧАТЬ
  
  На верх
  ==================================

Г О С У Д А Р С Т В Е Н Н Ы Й С Т А Н Д А Р Т С О Ю З А С С Р

Система технической документации на АСУ	ГОСТ 24.207-80
ТРЕБОВАНИЯ К СОДЕРЖАНИЮ ДОКУМЕНТОВ ПО ПРОГРАММНОМУ ОБЕСПЕЧЕНИЮ
System of technical documentation for computer control systems. Requirements for contents of documents on software

Постановлением Государственного комитета СССР по стандартам от 14 мая 1980 г. № 2101 срок введения установлен

с 01.01 1981 г.

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

1. ОБЩИЕ ПОЛОЖЕНИЯ

1.1. Документация программного обеспечения предназначена:

• для описания проектных решений по программному обеспечению в документе «Описание программного обеспечения АСУ».
• для установления требований к программе (комплексу программ) в документе «Техническое задание»;
• для описания решений, обеспечивающих сопровождение, изготовление и эксплуатацию программы (комплекса программ) в документах «Пояснительная записка», «Описание применения», «Описание программы», «Спецификация», «Руководство программиста», «Руководство оператора», «Текст программы», «Формуляр», «Порядок и методика испытаний»;
• для проверки работоспособности программы (комплекса программ) в документе «Описание контрольного примера».

1.2. При разработке документов на части АСУ содержание разделов каждого документа ограничивают рамками соответствующей части.

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

1.4. Требования к содержанию документов «Техническое задание», «Пояснительная записка», «Описание применения», «Спецификация», «Руководство оператора», «Текст программы», «Формуляр», «Порядок и методика испытаний» установлены ГОСТ 19.201-78 , ГОСТ 19.404-79 , ГОСТ 19.502-78 , ГОСТ 19.202-78 , ГОСТ 19.505-79 , ГОСТ 19.401-78 , ГОСТ 19.501-78 и ГОСТ 19.301-79 .

(Измененная редакция, Изм. № 1).

2. ТРЕБОВАНИЯ К СОДЕРЖАНИЮ ДОКУМЕНТОВ

2.1. Описание программного обеспечения АСУ

2.1.1. Документ должен содержать вводную часть и разделы:

• структура программного обеспечения;
• основные функции частей программного обеспечения;
• методы и средства разработки программного обеспечения;
• операционная система;
• средства, расширяющие возможности операционной системы.

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

2.1.3. Раздел «Структура программного обеспечения» должен содержать перечень частей программного обеспечения с указанием их взаимосвязей и обоснованием выделения каждой из них.

2.1.4. Раздел «Основные функции частей программного обеспечения» должен содержать подразделы, в которых для каждой части программного обеспечения приводят назначение и описание основных функций

(Измененная редакция, Изм. № 1).

2.1.5. Раздел «Методы и средства разработки программного обеспечения» должен содержать перечень методов программирования и средств разработки программного обеспечения АСУ с указанием частей программного обеспечения, при разработке которых следует использовать соответствующие методы и средства.

2.1.6. Раздел «Операционная система» должен содержать:

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

2.1.7. Раздел «Средства, расширяющие возможности операционной системы» должен содержать подразделы, в которых для каждого используемого средства, расширяющего возможности операционной системы, следует указать:

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

2.2. Описание программы

2.2.2. Для программы (комплекса программ), получаемой за счет использования ранее разработанных программных средств, документ «Описание программы» следует дополнять разделом «Настройка программных средств».

2.2.3. Раздел «Настройка программных средств» должен содержать:

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

2.3. Руководство программиста

2.3.1. Документ по составу разделов и их содержанию должен соответствовать ГОСТ 19.504-79 и, кроме того, включать раздел «Сведения о форме представления программы (комплекса программ)».

2.3.2. Раздел «Сведения о форме представления программы (комплекса программ)» должен содержать сведения о носителе, на котором записана программа, о содержании и системе кодирования информации, записанной на носителе, а также сведения, необходимые для чтения информации с носителя.

2.3.3. Для программы (комплекса программ), допускающей настройку на условия конкретного применения, в документ «Руководство программиста» включают разделы:

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

2.3.4. Разрешается для программы (комплекса программ), допускающей настройку на условия конкретного применения, вместо разделов, перечисленных в п. 2.3.3, разрабатывать отдельный документ «Руководство системного программиста», удовлетворяющий требованиям ГОСТ 19.503-79 .

2.4. Описание контрольного примера

2.4.1. Документ должен содержать разделы:

• назначение;
• исходные данные;
• результаты расчета;
• проверка программы (комплекса программ).

2.4.2. Раздел «Назначение» должен содержать перечень параметров и краткую характеристику функции, из числа реализуемых программой (комплексом программ), проверяемых контрольным примером.

2.4.3. Раздел «Исходные данные» должен содержать описание исходных данных для проверки программы (комплекса программ) с приведением исходных данных. Допускается исходные данные представлять в виде распечатки с АЦПУ.

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

2.4.5. Раздел «Проверка программы (комплекса программ)» должен содержать:

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

* Переиздание (май 1986 г.) с Изменением № 1, утвержденным в августе 1985 г. (ИУС 11-85).

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

Что такое стандарты на документацию?

В серии 34, о которой идет речь, существует всего 3 основных стандарта по документированию:

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

Это базовый документ, в котором приводится полный перечень документации ГОСТ 34, рекомендации по кодированию документов, к каким стадиям проекта относятся документы (стадии описываются в ГОСТ 34.601-90), а также как их можно объединить между собой.

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

Объемистый стандарт, с различной степенью детальности описывающий содержание проектных документов. В качестве индекса используется упомянутый выше ГОСТ 34.201-89.

К стандарту РД 50-34.698-90 существует множество вопросов и трактовок его положений, которые ввиду их неконкретности, часто понимают по-разному заказчик и исполнитель или даже члены проектной команды. Но ничего более конкретного у нас, к сожалению, нет.

Рассмотрим теперь плюсы и минусы стандартов, начав традиционно с минусов.

Минусы стандартов

Основной минус всем очевиден - стандарты старые. В них заложено устаревшее представление об архитектуре автоматизированной системы. Например:

• приложения двухуровневые, состоящие из клиентской программы и сервера СУБД (никаких трех- и более «уровневых» приложений, никаких Weblogic или JBoss)
• структура таблиц базы данных, будучи описана, даст представление о логической модели данных (то, что между приложением и базой может находиться какой-нибудь Hibernate, тогда казалось нехорошим излишеством)
• пользовательский интерфейс однооконный (а разве бывает другой? А что такое «браузер»?)
• Отчетов в системе немного, все они бумажные и печатаются на матричном принтере
• Разрабатываемая программа ориентирована на решение «задачи обработки информации», которая имеет четкий вход и выход и узко специализирована. В основе обработки информации лежит «алгоритм». Иногда «алгоритмов» бывает несколько. (Объектно-ориентированное программирование тогда делало лишь свои первые шаги и серьезно не рассматривалось).
• администратор базы данных понимает, какая информация лежит в таблицах и активно участвует в редактировании системных справочников (а разве бывает один сервер СУБД для 50 разных приложений?)

Соответственно, в стандарте есть артефакты, наподобие следующего:

5.8. Чертеж формы документа (видеокадра)
В документе должно быть приведено изображение формы документа или видеокадра в соответствии с требованиями государственных стандартов унифицированной системы документации Р 50-77 и необходимые пояснения.

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

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

Сейчас уже нам ничего не говорят слова «машинограмма», «видеокадр», «АЦПУ». Я тоже их не застал в употреблении, хотя заканчивал профильный институт в 90-е. Это было время появления Windows 3.1, VGA дисплеев, трехдюймовых дискет и первых отечественных интернет-сайтов. Но в стандарте эти слова есть, и заказчик иногда капризно требует предоставить ему полный комплект документации в соответствии с ГОСТ 34.201-89. Более того, подобные формулировки в ТЗ кочуют из одного министерства в другое и стали уже неким негласным шаблоном, в который вбивают содержательную часть.

Так что документ с дурацким названием «Чертеж формы документа (видеокадра)» в проекте должен быть и должен быть не пустым.

Что в стандарте хорошо

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

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

Когда вам требуется грамотно поставить задачу западным подрядчикам, которые про наши ГОСТы слыхом не слыхивали, можно также опираться на эти стандарты, а точнее на их контент, смысловую составляющую. Потому что, повторюсь, гарантия полноты информации дорогого стоит. Как бы мы себя не тешили высоким уровнем своего профессионализма, мы можем забыть включить в состав наших требований элементарные вещи, тогда как тот же ГОСТ 34.602-89 «помнит» обо всем. Если вам непонятно, как должен выглядеть результат работы западных подрядчиков, посмотрите на требования к документированию, к рекомендуемым разделам. Уверяю вас, лучше не придумать! Скорее всего, есть западные аналоги наших стандартов, в которых все может быть полнее, современнее и лучше. К сожалению, я с ними не знаком, так как не было пока ни одного случая, чтобы наших ГОСТов было бы недостаточно.

Можно смеяться над тем, что создатели стандартов ничего не знали о java или.NET, о HD мониторах и Интернете, но я бы не советовал недооценивать масштаб проделанной ими работы и ее ценность для нашего профессионального сообщества.

Как читать и понимать стандарты документации по ГОСТ серии 34

Стандарт делит все документы по двум осям - время и предметная область. Если посмотреть таблицу 2 в ГОСТ 34.201-89, то хорошо видно это деление (колонки «Стадия создания» и «Часть проекта»

Стадии создания АСУ

Стадии создания определены в ГОСТ 34.601-90. Имеют отношение к документированию из них три:

• Эскизный проект (ЭП)
• Технический проект (ТП)
• Разработка рабочей документации (РД)

Эскизный проект следует после стадии Техническое задание и служит для разработки предварительных проектных решений.

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

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

Части (разделы) проектной документации по созданию АСУ

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

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

Для того, чтобы полностью описать этот «автомат», сделаны следующие разрезы (как в черчении):

Математическое обеспечение (МО) , отвечающее на вопросы: какая логика зашита внутри «черного ящика»? Почему выбраны именно эти алгоритмы, именно такие формулы и именно такие коэффициенты?

Математическое обеспечение ничего не знает ни о процессорах, ни о базах данных. Это отдельная абстрактная область, обитель «сферических коней в вакууме». Но математическое обеспечение бывает очень плотно связано с предметной областью, aka Реальная жизнь. Например, управляющие алгоритмы для систем управления дорожным движением требуется согласовать в ГИБДД перед тем, как их будет согласовывать заказчик. И тут понимаешь, зачем их выделяют в отдельную книжицу. Потому что в ГИБДД никому не интересно, на какой ОС будет работать сервер приложения, а вот какой знак и ограничение скорости выскочит на табло в дождь или в снег очень даже интересно. Они отвечают за свою часть, и ничего другого подписывать не собираются. С другой стороны, когда они подписали, не будет вопросов к технической стороне вопроса - почему выбрали те, а не другие табло или светофоры. Мудрость «предков» как раз и проявляется в таких вот практических кейсах.

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

Или вот «Ведомость машинных носителей информации». Понятно, что раньше в нем были номера магнитных барабанов или бобин с пленкой. А сейчас что туда вносить?

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

Программное обеспечение (ПО) . Любимая всеми часть проектной документации. Да хотя бы потому, что это всего один документ! И потом, всем понятно, что туда нужно записывать. Но я, все-же, повторю.

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

Техническое обеспечение (ТО) . Не менее любимая всеми часть проектной документации. Радужную картину омрачает только обилие документов, которые требуется разрабатывать. Всего по стандарту требуется разработать 22 документа, из них 9 на стадии ТП.

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

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

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

На стадии ТП раздел содержит всего один документ «Описание организационной структуры », в котором мы должны рассказать заказчику, к чему он должен готовиться в плане изменения оргштатной структуры. Вдруг требуется организовать новый отдел для эксплуатации вашей системы, ввести новые должности и т.п.

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

Руководство пользователя . Комментарии излишни, я думаю.

Методика (технология) автоматизированного проектирования . В этот документ при необходимости можно поместить описание процесса сборки ПО, управления версиями, тестирования и т.п. Но это если в ТЗ заказчик желает самолично осуществлять сборку ПО. Если он этого не требует (и не платит за это), то вся ваша внутренняя кухня не его ума дело, и этот документ делать не нужно.

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

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

Технологическая инструкция является прослойкой между ОРД и руководством пользователя. РП подробно описывает как нужно делать те или иные действия в системе. Технологическая инструкция говорит о том, какие действия необходимо выполнять в тех или иных случаях, связанных с эксплуатацией системы. Грубо говоря, технологическая инструкция это краткий дайджест по РП для конкретной должности или роли. Если у заказчика роли не сформированы или он хочет, чтобы вы сами сформировали роли и требования к должностям, включите в документ самые базовые роли, например: оператор, старший оператор, администратор. Замечания заказчика на тему, «а у нас не так» или «а нам не нравится» должны сопровождаться перечнем ролей и описанием должностных обязанностей. Потому что бизнес-процессы мы не ставим . Мы эти бизнес-процессы автоматизируем .

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

Описание технологического процесса обработки данных (включая телеобработку) . Жалкий рудимент пещерного века, когда были специально выделенные «Операторы ЭВМ», скармливающие машине перфокарты и упаковывающие распечатку результата в конвертик. Эта инструкция - для них. Что в нее писать в XXI веке - я вам точно сказать не могу. Выкручивайтесь сами. Самое лучшее, это просто забыть про этот документ.

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

А в-третьих, в состав ОР входит мега-документ под названием «Пояснительная записка к техническому проекту», который по задумке представляет собой некий Executive Summary, а по факту многие проектанты пихают в него вообще все полезное содержание стадии ТП. Подобный радикальный подход бывает оправдан и даже взаимно выгоден и заказчику и исполнителю работ, но в определенных случаях.

Варианты использования ГОСТ 34

1. Полное и точное следование стандарту . Добровольно никто, естественно, такую тучу документов писать не будет. Поэтому полный комплект документов готовится только по настоятельной просьбе заказчика, которую он закрепил в ТЗ и еще договором сверху придавил. В таком случае требуется понимать все буквально и отдать заказчику физические «книжки», на которых будут стоять названия документов из таблицы 2 ГОСТ 34.201-89 за исключением совсем уж ненужных, перечень которых вы обязательно должны обговорить и закрепить письменно. Содержание документов также должно без всякой фантазии соответствовать РД 50-34.698-90, вплоть до названия разделов. Для того, чтобы у заказчика взорвался мозг, иногда большую систему делят на подсистемы, и для каждой подсистемы выпускают отдельную проектную документацию. Выглядит это устрашающе и нормальному контролю при помощи земного разума не подлежит. Особенно в части интеграции подсистем. Что значительно упрощает приемку. Главное, чтобы вы сами при этом не запутались и чтобы ваша система все-таки заработала как надо.
2. Мы просто любим ГОСТы . В серьезных больших компаниях любят стандарты. Потому, что они помогают людям лучше понимать друг друга. Если ваш заказчик замечен в любви к порядку и стандартизации, постарайтесь придерживаться стандартной идеологии ГОСТ при разработке документов, даже если этого не требует ТЗ. Вас лучше поймут и одобрят согласующие специалисты, а вы сами не забудете включить в документацию важную информацию, лучше будете видеть целевую структуру документов, точнее планировать работы по их написанию и сэкономите себе и коллегам массу нервов и денег.
3. Нам плевать на документацию, лишь бы все работало . Исчезающий вид безответственного заказчика. Подобный взгляд на документацию пока еще можно встретить у небольших и бедных заказчиков, а также в оставшихся со времен перестройки авторитарных «идиотократиях», где босс окружен верными друзьями - директорами, и все вопросы решаются в личных беседах. Вы вольны в подобных условиях забивать на документирование вообще, но лучше, все таки, прицел не сбивать и хотя бы схематично наполнять содержимым документацию. Если не этому заказчику, так следующему передадите (продадите).

Заключение

Эта статья была о наших ГОСТах на документирование АСУ. ГОСТы старые, но, как оказалось, до сих пор очень даже полезные в хозяйстве. Не считая некоторые явные рудименты, структура документации обладает свойствами полноты и непротиворечивости, а следование стандарту снимает многие проектные риски, о существовании которых мы можем по началу не догадываться.

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

Г О С У Д А Р С Т В Е Н Н Ы Й С Т А Н Д А Р Т С О Ю З А С С Р

Единая система программной документации	ГОСТ 19.101-77 (СТ СЭВ 1626-79)
ВИДЫ ПРОГРАММ И ПРОГРАММНЫХ ДОКУМЕНТОВ
United system for program documentation. Types of programs and program documents

Дата введения с 01.01.80

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

Стандарт полностью соответствует СТ СЭВ 1626-79.

1. ВИДЫ ПРОГРАММ

1.1. Программу (по ГОСТ 19781-90) допускается идентифицировать и применять самостоятельно и (или) в составе других программ.

1.2. Программы подразделяют на виды, приведенные в табл. 1

Таблица 1

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

1.2,1.3.

2. ВИДЫ ПРОГРАММНЫХ ДОКУМЕНТОВ

2.1. К программным относят документы, содержащие сведения, необходимые для разработки, изготовления, сопровождения и эксплуатации программ.

2.2. Виды программных документов и их содержание приведены в табл. 2.

Таблица 2

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

(Измененная редакция, Изм. № 1).

2.3. Виды эксплуатационных документов и их содержание приведены табл.3.

Таблица 3

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

(Измененная редакция, Изм. № 1).

2.4. В зависимости от способа выполнения и характера применения программные документы подразделяются на подлинник, дубликат и копию (ГОСТ 2.102-68), предназначенные для разработки, сопровождения и эксплуатации программы.

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

Таблица 4

Код вида документа	Вид документа	Стадии разработки
		Эскизный проект	Технический проект	Рабочий проект
				компонент	комплекс
-	Спецификация	-	-
05	Ведомость держателей подлинников	-	-	-
12	Текст программы	-	-
13	Описание программы	-	-
20	Ведомость эксплуатационных документов	-	-
30	Формуляр	-	-
31	Описание применения	-	-
32	Руководство системного программиста	-	-
33	Руководство программиста	-	-
34	Руководство оператора	-	-
35	Описание языка	-	-
46	Руководство по техническому обслуживанию	-	-
51	Программа и методика испытаний	-	-
81	Пояснительная записка			-	-
90-99	Прочие документы

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

2.2-2.5. (Измененная редакция, Изм. № 1).

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

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

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

Технические условия разрабатывают на стадии «Рабочий проект».

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

(Введен дополнительно, Изм. № 1).

Переиздание (Ноябрь 1987 г.) с Изменением № 1, утвержденным в июне 1981 г (ИУС 9-81)