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

Единая система документации программной продукции – ЕСПД – относится к ГОСТ класса 19 и подразделяется на 10 групп:
1. Основополагающие стандарты.
2. Правила выполнения документации разработки.
3. Правила выполнения документации изготовления.
4. Правила выполнения документации сопровождения.
5. Правила выполнения эксплуатационной документации.
6. Правила обращения программной документации.

Стандарт с номером 0 содержит общие положения, стандарты 7 и 8 являются зарезервированными и к номеру 9 относятся прочие стандарты, не вошедшие в первые 6.

Это краткие описания ГОСТов класса 19, для более подробного ознакомления с ними необходимо обратиться к справочникам.

ГОСТ 19.001-77 – единая система программной документации.
ГОСТ 19.101-77 – виды программ и программных документов.
ГОСТ 19.102-77 – стадии разработки программ и программной документации.
ГОСТ 19.105-78 – требования к оформлению программных документов, комплексов и систем независимо от их назначения и области применения. ГОСТ 19.105-78 содержит полный перечень документации, которая должна сопровождать законченный программный продукт.

Перечень документации, декларируемой ГОСТ 19.105-78:

1. Документы, содержащие сведения, необходимые для разработки программного продукта, его изготовления.
1.1. Спецификация – состав программы и документации на нее.
1.2. Ведомость держателей подлинников – перечень предприятий, на которых хранятся подлинники программной документации.
1.3. Текст программы – запись текста программы с необходимыми комментариями.
1.4. Описание программы – сведения о логической и функциональной структуре программы.
1.5. Программа и методика испытаний – требования, подлежащие проверке при испытании программы, порядок и методы их контроля.
1.6. Техническое задание – назначение и область применения программы, технические и специальные требования, необходимые стадии и сроки разработки, виды испытаний.

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

2. Документы, используемые при эксплуатации программного продукта.
Ведомость эксплуатационных документов – перечень эксплуатационных документов на программу.
Формуляр – основные характеристики программы, комплектность, общие сведения об эксплуатации программы.
Описание применения – сведения о назначении программы, области применения, классе решаемых задач, ограничения на применение, необходимая конфигурация технических средств.
Руководство системного программиста – сведения для проверки и обеспечения функциональности, настройки программы.
Руководство программиста – сведения для эксплуатации настроенной программы.
Руководство оператора – сведения для обеспечения процедуры общения оператора с ЭВМ в процессе выполнения программы.
Описание языка – описание синтаксиса и семантики языка, используемого в программе.
Руководство по техническому обслуживанию – сведения для применения тестовых программ при обслуживании технических средств.

Другие ГОСТы класса 19:

ГОСТ 19.201-78 – порядок построения и оформления технического задания на разработку программы или программного изделия.
ГОСТ 19.202-78 – форма и порядок составления спецификации на программные продукты, определяемые в ГОСТ 19.101-77.
ГОСТ 19.301-79 – программа и методика испытаний программных продуктов.
ГОСТ 19.401-78 – порядок построения и оформления текста программы при разработке программных продуктов.
ГОСТ 19.402-78 – описание программы.
ГОСТ 19.403-79 – форма заполнения и содержание ведомости держателей подлинников, определяемой в ГОСТ 19.105-78.
ГОСТ 19.404-79 – форма заполнения и содержание пояснительной записки, определяемой в ГОСТ 19.105-78.
ГОСТ 19.501-78 – форма заполнения и содержание формуляра на программный продукт, определяемый в ГОСТ 19.105-78.
ГОСТ 19.502-78 – форма заполнения и содержание описания применения, определяемого в ГОСТ 19.105-78.
ГОСТ 19.503-79 – форма заполнения и содержание руководства системного программиста, определяемого в ГОСТ 19.105-78.
ГОСТ 19.504-79 – форма заполнения и содержание руководства программиста, определяемого в ГОСТ 19.105-78.
ГОСТ 19.505-79 – форма заполнения и содержание руководства оператора, определяемого в ГОСТ 19.105-78.
ГОСТ 19.506-79 – форма заполнения и содержание описания языка, определяемого в ГОСТ 19.105-78.
ГОСТ 19.507-79 – форма заполнения и содержание ведомости эксплуатационных документов, определяемой в ГОСТ 19.105-78.
ГОСТ 19.508-79 – форма заполнения и содержание руководства по техническому обслуживанию, определяемому в ГОСТ 19.105-78.
ГОСТ 19.701-90 – схемы алгоритмов, программ, данных и систем.

4.1. Требования к системе в целом.

4.1.1. Требования к структуре и функционированию системы.
4.1.2. Требования к численности и квалификации персонала системы и режиму его работы.
4.1.3. Требования к надежности.
4.1.4. Требования безопасности.
4.1.5. Требования к эргономике и технической эстетике.
4.1.6. Требования к эксплуатации и техническому обслуживанию.
4.1.7. Требования к защите информации от несанкционированного доступа;
4.1.8. Требования к сохранности информации при авариях.
4.1.9. Требования к защите от влияния внешних воздействий.
4.1.10. Требования к патентной чистоте.
4.1.11. Любые дополнительные требования.

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

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

4.3. Требования к видам обеспечения.

4.3.1. Требования к математическому обеспечению системы.

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

4.3.2. Требования информационному обеспечению системы.

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

4.3.3. Требования к лингвистическому обеспечению системы.

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

4.3.4. Требования к программному обеспечению системы.

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

4.3.5. Требования к техническому обеспечению.

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

4.3.6. Требования к организационному обеспечению.

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

ИСПОЛЬЗОВАНИЕ ТРЕБОВАНИЙ ГОСТ 19 и 34 СЕРИИ ПРИ ОФОРМЛЕНИИ ДОКУМЕНТАЦИИ В IT-ПРОЕКТАХ ДЛЯ ГОСУДАРСТВЕННЫХ СТРУКТУР

Введение

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

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

При разработке автоматизированных систем (АС) по ГОСТ 34 в IT-проектах для госструктур зачастую возникает вопрос: по каким ГОСТам оформлять документацию? В ГОСТ 34 нет явных указаний на то, по каким стандартам оформлять конкретные документы, разрабатываемые в рамках создания АС, кроме требований к оформлению ТЗ. Попробуем выяснить, какие ГОСТы используются при оформлении документов в случае отсутствия точных указаний в государственном контракте или конкурсном техническом задании (ТЗ). Данный материал в первую очередь, предназначен для IT-специалистов, желающих разобраться, как оформляются документы в IT-проектах по требованиям ГОСТ.

Определение стандартов оформления документации

Оформление документов в ГОСТ 34 зависит от вида документа (конструкторский или программный), и стадии создания АС, на которой готовится документ.

Перечень документов, разрабатываемых на различных стадиях создания АС приведен в ГОСТ 34.201-89 «Виды, комплектность и обозначение документов при создании автоматизированных систем». В нем приведены следующие требования:

На стадии «Техническое задание» разрабатывают ТЗ на создание АС по ГОСТ 34.602 -89 «Техническое задание на создание автоматизированной системы»;
Виды программных документов ГОСТ 19.101-77 «Единая система программной документации. Виды программ и программных документов». К ним относятся различные руководства, например, руководство пользователя.
Виды конструкторских документов , разрабатываемых на различных стадиях создания АС определяются по ГОСТ 2.102-2013 «Единая система конструкторской документации. Виды и комплектность конструкторских документов». Например, к ним относятся ведомости эскизного и технического проекта, ведомость покупных изделий, пояснительные записки к эскизному, техническому проектам.

Теперь разберем подробнее, как определить стандарты оформления в различных проектах.

Оформление ТЗ

С ТЗ всё достаточно ясно: в ГОСТ 34.602-89 приведен стандарт его оформления: п.3.2. гласит, что «ТЗ на АС оформляют в соответствии с требованиями ГОСТ 2.105 на листах формата А4 по ГОСТ 2.301 без рамки, основной надписи и дополнительных граф к ней».

Оформление программной документации

С программными документами, разрабатываемыми в рамках ИТ-проекта, также есть чёткое указание использовать ГОСТ 19 серии в части оформления: вышеприведённый ГОСТ 19.101-77 входит в серию ГОСТов 19-й серии «Единая система программной документации» (ЕСПД). ЕСПД - комплекс государственных стандартов Российской Федерации, устанавливающих взаимосвязанные правила разработки, оформления и обращения программ и программной документации.

Документация в ЕСПД оформляется по ГОСТ 19.104-78 «Единая система программной документации. Основные надписи», ГОСТ 19.105-78 «Единая система программной документации. Общие требования к программным документам», ГОСТ 19.106-78 «Единая система программной документации. Требования к программным документам, выполненным печатным способом».

Оформление конструкторской документации

Теперь рассмотрим ГОСТ 2.102-2013. Этот стандарт входит в серию ГОСТов 2-й серии «Единая система конструкторской документации» (ЕСКД). ЕСКД - межгосударственный комплекс стандартов, устанавливающих взаимосвязанные нормы и правила по разработке, оформлению и обращению конструкторской документации, разрабатываемой и применяемой на всех стадиях жизненного цикла изделия (при проектировании, изготовлении, эксплуатации, ремонте и др.)

Документация в ЕСКД оформляется по нескольким стандартам. Наиболее часто используемыми из них (применительно к ИТ-сфере) являются ГОСТ 2.105-95 «Единая система конструкторской документации. Общие требования к текстовым документам» и ГОСТ 2.106-96 «Единая система конструкторской документации. Текстовые документы».

На первый взгляд из ГОСТ 34 серии непонятно, как оформлять документацию на АС. Нередко в рамках ИТ-проекта, особенно для государственных заказчиков, в ТЗ бывают требования по оформлению документации согласно ГОСТ 2.105-95 и ГОСТ 2.106-96. Но следует ли оформлять документы по этим ГОСТам в случае, если в явном виде требования к оформлению отсутствуют?

Как правильно оформить?

В ГОСТ 2-й серии приведены требования к назначению каждого стандарта и обозначена отрасль его применения: ГОСТ 2.102-2013 – стандарт устанавливает виды и комплектность конструкторских документов на изделия всех отраслей промышленности.

Если ГОСТ 2.102-2013 распространяется на изделия всех отраслей, в том числе и ИТ-сферу, давайте разберёмся, а что является конструкторским документом?

Согласно ГОСТ 2.001-2013 «Единая система конструкторской документации (ЕСКД). Общие положения»:

А) «3.1.2 конструкторский документ: Документ, который в отдельности или в совокупности с другими документами определяет конструкцию изделия и имеет содержательную и реквизитную части, в том числе установленные подписи»

Б) «3.1.5 конструкторская документация: Совокупность конструкторских документов, содержащих данные, необходимые для проектирования (разработки), изготовления, контроля, приемки, поставки, эксплуатации, ремонта, модернизации, утилизации изделия»

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

Основные ГОСТы 2-й серии для ИТ-проекта в части оформления

Теперь посмотрим на основные ГОСТы 2-й серии, наиболее часто применяемые для оформления документов в ИТ-проекте. Как правило, в части оформления используют:

ГОСТ 2.105-95 – стандарт устанавливает общие требования к выполнению текстовых документов на изделия машиностроения, приборостроения и строительства;

ГОСТ 2.106-96 – стандарт устанавливает формы и правила выполнения конструкторских документов изделий машиностроения и приборостроения.

У читателя может возникнуть вопрос, можем ли мы применять эти ГОСТы для АС, если они предназначены для изделий машиностроения и приборостроения?

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

Кроме этого, если заглянуть в ГОСТ 34.003-90 «Автоматизированные системы. Термины и определения», этот стандарт определяет АС как «систему, состоящую из персонала и комплекса средств автоматизации его деятельности, реализующую информационную технологию выполнения установленных функций».

Таким образом, АС относится к отрасли приборостроения и, следовательно, конструкторские документы АС оформляются по ГОСТ 2.105-95 и ГОСТ 2.106-96.

Теперь давайте рассмотрим основные моменты оформления проектной документации по ГОСТ 2.105-95 и ГОСТ 2.106-96.

Основные моменты при оформлении по ГОСТ 2. 105

Рассмотрим основные параметры оформления по ГОСТ 2-й серии.

Согласно ГОСТ 2.105-95 расстояние от рамки формы до границ текста в начале и в конце строк должно быть не менее 3 мм. Расстояние от верхней или нижней строки текста до верхней или нижней рамки должно быть не менее 10 мм. Абзацы в тексте начинают отступом, равным пяти ударам пишущей машинки (15 - 17 мм).

В ГОСТ 2.105-95 не определены параметры для оформления текста в электронном виде: название шрифта, высота шрифта, межстрочный интервал. Поэтому параметры оформления документов в электронном виде это, как правило, предмет договоренности с заказчиком.

В начале работы по оформлению в электронном виде определяются параметры для форматирования:

Формат абзацев текста – используемый шрифт, высота шрифта, размер межстрочного интервала;
Формат для каждого заголовка по уровням (1, 2, 3) – используемый шрифт, высота шрифта, отступ в см, размер межстрочного интервала;

Таблица - используемый шрифт текста, межстрочный интервал, толщина границ таблицы, ширина таблицы, отступ в ячейке, название размещается над таблицей. Форматирование названия Таблицы выполняется таким же образом, как у основного текста документа. По ГОСТ 2.105-95 высота строк таблицы должна быть не менее 8 мм. Высота шрифта строк таблицы также может быть согласована с заказчиком.

Иллюстрации в документе следует располагать по центру. Название размещается непосредственно под иллюстрацией. Форматирование названия – как у текста документа.

Правила оформления таблиц

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

Таблицы, за исключением таблиц приложений, нумеруют арабскими цифрами сквозной нумерацией. Например: «Таблица 1».

Таблицы каждого приложения обозначают отдельной нумерацией арабскими цифрами с добавлением перед цифрой обозначения приложения. Например: «Таблица В.1».

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

Название таблицы должно отражать ее содержание, быть точным, кратким. Название состоит из слова «Таблица», номера таблицы и текста. В ГОСТ 2.105-95 не определено использование в названии таблицы дефиса или тире. На практике может использоваться тире, по аналогии использования в названии рисунка тире. Например, «Таблица 5 – Выполняемые работы, содержание и сроки». Точка в конце названия не ставится. Название размещают над таблицей слева.

В ГОСТ 2.105-95 в п.п 4.4.3 приведено следущее требование: «На все таблицы документа должны быть приведены ссылки в тексте документа, при ссылке следует писать слово «таблица» с указанием ее номера». На практике слово «таблица» склоняется в тексте по правилам русского языка. Например: «Краткое описание назначения и основных характеристик подсистем ИС МП второй очереди представлено в таблице 1».

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

В ГОСТ 2.105-95 есть необязательное требование в п.4.4.7: «если в конце страницы таблица прерывается и ее продолжение будет на следующей странице, в первой части таблицы нижнюю горизонтальную линию, ограничивающую таблицу, допускается не проводить.». На практике нижнюю горизонтальную линию, проводят, так ее отсутствие ухудшает восприятие таблицы пользователем.

Правила оформления иллюстраций

К иллюстрациям относятся графические изображения (схемы, графики, фотографии, рисунки).

Иллюстрации, за исключением иллюстраций приложений, нумеруются арабскими цифрами, при этом нумерация сквозная. Например: «Рисунок 3».

Иллюстрации каждого приложения обозначают отдельной нумерацией арабскими цифрами с добавлением перед цифрой обозначения приложения. Например: «Рисунок В.6».

Допускается нумеровать иллюстрации в пределах раздела. В этом случае номер иллюстрации состоит из номера раздела и порядкового номера иллюстрации, разделенных точкой. Например, в разделе 5 номер будет «Рисунок 5.2».

Допускается не нумеровать мелкие иллюстрации (мелкие рисунки), размещенные непосредственно в тексте и на которые в дальнейшем по тексту нет ссылок.

Требования ГОСТ 2.105-95 к расположению: «иллюстрации могут быть расположены как по тексту документа (возможно ближе к соответствующим частям текста), так и в конце его».

В ГОСТ 2.105-95 в п. 4.3.1 указано следующее: «при ссылках на иллюстрации следует писать "... в соответствии с рисунком 2" при сквозной нумерации и "... в соответствии с рисунком 1.2" при нумерации в пределах раздела».

Название пишется под иллюстрацией в формате «Рисунок 1 – Детали прибора».

Интересный факт: если ошибку в бумажном документе замазать и поверх написать исправление черными чернилами, это будет по ГОСТу. ГОСТ 2.105-95 допускает исправления документов в бумажном виде. Об этом гласит п.3.7: «Опечатки, описки и графические неточности, обнаруженные в процессе выполнения документа, допускается исправлять подчисткой или закрашиванием белой краской и нанесением на том же месте исправленного текста (графика) машинописным способом или черными чернилами, пастой или тушью рукописным способом. Повреждения листов текстовых документов, помарки и следы не полностью удаленного прежнего текста (графика) не допускаются».

То есть, если вы что-то распечатали и нашли ошибку, то её можно исправить вручную приведенным выше способом.

Оформление по ГОСТ 2. 106-96

ГОСТ 2.106-96 устанавливает формы и правила выполнения конструкторских документов. Для каждого типа документа в ГОСТ 2.106-96 приведен шаблон оформления рамок документа.

ГОСТ 2.106-96 определяет не только форму рамок, но и основную надпись в рамке. Пример из ГОСТ 2.106-96: «ПЗ составляют на формах 9 и 9а приложения А, а необходимые схемы, таблицы и чертежи в бумажной форме допускается выполнять на листах любых форматов, установленных ГОСТ 2.301, при этом основную надпись и дополнительные графы к ней выполняют в соответствии с требованиями ГОСТ 2.104 (форма 2а)».

Резюме

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

Программные документы, разрабатываемые на различных стадиях создания АС оформляются по ГОСТ 19.104-78, ГОСТ 19.105-78, ГОСТ 19.106-78;
Конструкторские документы, разрабатываемые на различных стадиях создания АС оформляются по ГОСТ 2.105-95 и ГОСТ 2.106-96. При этом требования к содержанию регламентируются РД 50.34-698-90.

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

Зачем, в принципе, нужны при проектировании?

Получается так, что ГОСТы помогают самому проектировщику.

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

Возникает интересный вопрос: а кому нужно и все эти пояснительные записки, ТЗ и т.п.? И вот какой интересный ответ у нас получится: на 85% документирование необходимо исполнителю. Оставшиеся 15% нужны заказчику для некоего общего понимания происходящего. Но исполнителю надо четко обозначить как границы проекта, так и признаки его выполнения. Исполнитель должен уметь защищать себя от хаотичности мышления заказчика.

Итак, обратимся к ГОСТам разработчика. Основных у нас их два: ГОСТ 34й серии и ГОСТ 19й серии. 34я серия относится к разработке автоматизированных систем, а 19й – к разработке программного обеспечения.
Мы будем говорить о ГОСТе 34й серии.

В 34й серии много различных ГОСТов. Нас будут интересовать лишь некоторые из них. А именно:

1. ГОСТ 34.003-90 Информационная технология. Комплекс стандартов на автоматизированные системы. Термины и определения
2. ГОСТ 34.601-90 Информационная технология. Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Стадии создания
3. ГОСТ 34.602-89 Информационная технология. Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы
4. ГОСТ 34.603-92 Информационная технология. Виды испытаний автоматизированных систем
5. ГОСТ 34.201-89 Информационная технология. Комплекс стандартов на автоматизированные системы. Виды, комплектность и обозначение документов при создании автоматизированных систем
6. РД 50-34.698-90 Автоматизированные системы. Требования к содержанию документов.

ГОСТы чем-то похожи по своей иерархической структуре на каталог. На такой, например, как Active Directory. Вероятно, что если писать документацию четко следуя ГОСТам, то перекрестные ссылки позволят вам ознакомиться с огромным количеством документов. Но что самое главное в ГОСТах, это четкая модель «от общего к частному». Начиная с общих фраз мы дойдем до самого последнего RJ45 в системе.

А теперь более подробно. Основным ГОСТом, вокруг которого идет т.н. пляска является ГОСТ 34.601-90 (Стадии создания). Давайте более подробно посмотрим на этот документ.

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

Как я говорил выше, ГОСТы содержат в себе перекрестные ссылки. И чтобы пойти дальше в наших рассуждениях, мы чуть-чуть заглянем в ГОСТ 34.003-90 (Термины и определения). В нем интересует определение автоматизированной системы. Это важно, т.к. нам все же надо иметь представление, что же мы собираемся создавать.

ГОСТ 34.003-90 в определении автоматизированной системы говорит нам следующее: автоматизированная система; АС: Система, состоящая из персонала и комплекса средств автоматизации его деятельности, реализующая информационную технологию выполнения установленных функций. Т.е. другими словами, АС состоит из

1. Персонала
2. комплекса средств
3. некой деятельности, подлежащей автоматизации.

Так же уточним у ГОСТа 34.003-90

1. комплекс средств автоматизации автоматизированной системы; КСА АС: Совокупность всех компонентов АС, за исключением людей
2. пользователь автоматизированной системы; пользователь AC: Лицо, участвующее в функционировании АС или использующее результаты ее функционирования
3. эксплуатационный персонал автоматизированной системы; эксплуатационный персонал АС
4. компонент автоматизированной системы; компонент AC: Часть АС, выделенная по определенному признаку или совокупности признаков и рассматриваемая как единое целое

Итак, что же у нас получается? А получается, что мы почувствовали под ногами некоторый фундамент, на который будем опираться. Нам известно, из чего состоит автоматизированная система и уточнили, что персонал бывает двух видов: пользовательский и эксплуатационный. И логически выведем, что компонент АС, выделенный по определенному признаку будет т.с. «hardware» и «software», если совсем просто. И совокупность программы+железо будет комплекс средств автоматизации АС.

Значит, если заказчик, например, скажет «А установите мне Exchange», то это не будет АС по одной простой причине: как минимум в таком задании отсутствует вид автоматизируемой деятельности. А может быть заказчику вообще нужен не Exchange. А может ему совсем нужен не Exchange. А это значит, что требуется обследование объекта автоматизации. А значит начинается стадия первая ГОСТ 34.601-90 (Стадии создания). «Формирование требований к АС»

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

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

В концепции нам необходимо изучить объект, где требуется произвести внедрение. Если в первой стадии мы искали причину создания АС вообще(исходя лишь из бизнес-целей, просто ГОСТ писался тогда, когда таких слов не употребляли), то на второй стадии нам необходимо найти возможные варианты, которые удовлетворяют требованиям заказчика. Например, если заказчик хочет почтовую систему, то это можно реализовать как на Exchange, так и на Postfix или на чем ни будь еще. Со своими плюсами, минусами и вариантами развития. Проводится общая экспертиза объекта и предварительно оцениваются трудозатраты. Мы, как исполнители, тоже ищем для себя наиболее оптимальный вариант.
После того, как мы придем с заказчиком к определенному единому мнению о том, какой именно вариант решения ему подходит в общих чертах больше всего, мы переходим к, не побоюсь этого слова, самому важному пункту проекта «Техническое задание»

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

ТЗ настолько важный документ, что ему посвящен персональный ГОСТ. Сейчас мы на этом подробно останавливаться не будем. Замечу лишь, что для правильного формирования ТЗ необходимо, чтобы стадии ГОСТа 34.601-90 «Формирование требований к АС» и «Разработка концепции АС» были выполнены. От качества выполнения этих стадий зависит правильность и корректность создания ТЗ.

Оставьте свой комментарий!

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

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

В серии 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

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

Заключение

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

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