Удобная памятка и 8 ссылок на документацию по ГОСТ 34 (автоматизированные системы)

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

    gost_1.png

    Так выглядит памятка и вот ссылка для скачивания, распечатки и вывешивания на почетное место.

    gost_2.jpg

    Для вашего удобства собрал ссылки на приведенные документы. В принципе этого будет достаточно, чтобы удовлетворить запросы самого требовательного заказчика. Некоторым из этих стандартов скоро исполнится 30 лет, и частично они могут не отвечать современным запросам. Но по полноте охвата (а о некоторых вещах вы могли и не подумать) им нет равных в ИТ. Если вы только начинаете свой карьерный путь, рекомендую хотя бы раз взглянуть на эти документы, чтобы потом уже не ломать голову над последовательностью создания и составом этих документов. А уж эта брошюра просто must have на стене у вашего рабочего места.

    ГОСТ 34.003-90 Термины и определения

    ГОСТ 34.201-89 Виды, комплектность и обозначение документов при создании автоматизированных систем

    ГОСТ 34.601-90 ГОСТ 34.601-90. Автоматизированные системы. Стадии создания

    ГОСТ 34.602-89 Техническое задание на создание автоматизированной системы

    ГОСТ 34.603-92 Виды испытаний автоматизированных систем

    РД 50-34.698-90 Автоматизированные системы. Требования к содержанию документов

    ЕСКД (ГОСТ 2) Единая система конструкторской документации

    ЕСПД (ГОСТ 19) Единая система программной документации

    Расскажите, насколько часто вам приходится иметь дело с ГОСТами этой серии и насколько удается применять эти рекомендации в процессе составления документации. А ниже — небольшой опрос. Заранее большое спасибо за обратную связь!

    Автор статьи: Антон Касимов, архитектор систем управления, компания «Инфосистемы Джет».

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

    В каких случаях вы оформляете проектную документацию на автоматизированную систему в соответствии с ГОСТ?

    Инфосистемы Джет
    488,54
    Системный интегратор
    Поделиться публикацией

    Комментарии 23

      +1
      А страшные шрифты для рамки разве не прописаны в ГОСТе?
        0
        Эти леденящие кровь вещи можно найти в ЕСКД (ГОСТ 2)
        +2
        Искренне сочувствую всем тем кому по этой херне приходится работать. К сожалению результатами Гостофикации ИТ можно только подтереться. За примерами ходить далеко не надо. Можно любую документацию по любому продукту выполненную по ГОСТу посмотреть.
          0
          Ну, если подойти к делу творчески, то получается вполне неплохо. Я бы даже сказал, что это стоит потраченного времени. Но только после написания кода. Например, я свой код очень легко передал коллеге, т.к. у меня было вменяемое описание программы, её назначения, структуры, модулей и их API, и даже алгоритмы были разрисованы. Другое дело, что заниматься этим следует не программисту, а техническому писателю. Я сейчас для рисования блок-схем нанимаю фрилансеров. В принципе, ничего страшного ГОСТ на ИТ не требует — руководства программиста, руководство оператора, и прочее. Но для его использования ГОСТ нужно, по-сути, переписывать на ходу, подгоняя под современные реалии, т.к. многое писалось ещё с оглядкой на ЕС ЭВМ, не под GUI, там у них какие-то сообщения постоянно, команды и прочие консольные реалии. Для описания консольных утилит вполне подойдёт. Если у Вас GUI и ООП — тогда нужно творчески переосмысливать, придумывать на ходу. Это можно делать — ГОСТ устарел, значит он сам виноват.
            +1
            ГОСТ-ы следует применять творчески, сообразно с обстоятельствами. А для того чтобы уверенно это делать — нужно представлять, что в них написано. Возьмём документ 34.601-90, он самый короткий из перечисленных.
            Что плохого в том, что он требует написания концепции? Да ничего плохого в этом нет, наоборот хорошо. Даже для маленького сайта, разрабатываемого стартапом из трёх человек — соберитесь в кафе, договоритесь между собой, напишите на салфетке, что сайт должен делать то-то для тех-то, писать мы его будем, условно, на python+django, размещать на хостинге с использованием контейнерной виртуализации. Назовите этот документ концепцией, и дальше ей следуйте. Это убережёт от массы лишних движений и потенциальных переделок.
            И будет у вас документация (сюрприз!) — в точном соответствии с ГОСТ-ом, но в объеме, потребном именно для этого небольшого проекта. Вырастет проект — на определённом этапе его доработки придёте к необходимости ТЗ. Опять же, не надо писать все разделы — напишите только нужные. ГОСТ 34.602-89 это явно разрешает.
            +2
            По работе приходится использовать ГОСТы. Приходилось оформлять по ним и схемы, и текстовые документы — инструкции, эксплуатационные документы. Когда стал заниматься программированием, приходилось заниматься и оформлением программной документации по ЕСПД.
            Общее впечатление от этого дела — нужная штука там, где необходима поддержка продукта. Т.е. если жизненный цикл продукта будет дольше, чем время работы специалиста на предприятии, то нужно оформлять документацию по какому-либо стандарту. Именно ГОСТ, наверное, не обязательно, но некоторый стандарт должен быть. Опять же, зависит от изделия. Если Вы делаете сложный продукт или продукт для массового производства — тогда необходимо. Если Вы делаете что-то для кустарного производства, то не обязательно строго следовать стандартам, достаточно заметок «на полях». Если программа или продукт — это что-то простое, тогда документация вообще не нужна — быстрее его реверснуть в уме или перепроектировать, нежели копаться в документации.
            В целом, ГОСТы во много устарели. В частности, ЕСПД требует разработку алгоритмов до написания программы. Ф. Брукс осуждает такой подход (он, видимо, списан с ИСО-шных гостов), говорит, что блок-схемы вообще не нужны. ГОСТ не предусматривает диаграмм классов, и прочего. Только блок-схемы, имеющие смысл лишь для процедурной парадигмы. Если у Вас ООП, то приходится изобретать.
            Плюсы применения ГОСТов появляются лишь тогда, когда продукт живёт долго. Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт. Минус ГОСТов — время на разработоку документации по стандарту (и время на внедрение стандарта).
            ГОСТы часто приходится применять и усовершенствовать с оглядкой на современные технологии. Запилить диаграмму классов в ГОСТовской рамке — вот Вам и новый программный документ. Хотя все диаграммы идут в составе инструкций программиста и описаний. Просто для них не предусмотрены обозначения. Придумываете сами (или заимствуете у иностранцев). ГОСТ это позволяет делать, если в самом ГОСТе нет обозначений.
            В целом, ГОСТ вполне себе неплох. Современные САПР позволяют лепить КД в ГОСТе, прямо в процессе построения схем, эмуляции и построении трёхмерных моделей. С технологией производства это тоже сопрягут со временем, т.е. можно будет по модели листового тела получить и чертёж, программу для лазерного станка, и т.п.
            По сути, КД и ПД — это продукт. И только владельцу предприятия решать, какой продукт должно производить его предприятие — отгружаемый заказчику или бумажный. И распределять усилия сотрудников.
            Да, самое главное — на большинстве предприятий для оформления текстовых документов держат специальных технических писателей. Для оформления чертежей раньше были чертёжники, которые работали на инженеров. С развитием САПР стало считаться, что конструктор сам в состоянии справится с оформлением КД.
              0
              >Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт.
              Категорически не согласен. Если бы разработка реальных продуктов шла по гостам никто бы вообще ни во что не врубался. Гост это сугубо формальный подход т.е. когда пишут не то что нужно, а то что требует Гост.

              За примерами ходить далеко не надо — откройте любой большой проект на github который развивается 5-7 лет и посмотрите как там разработка устроена и документирование.

                0
                Ну, всё зависит от того, кто пишет документацию. Если пишется для того, чтобы отвязались, тогда документация получается такая, как Вы пишете. Если пишут на совесть, то получается хорошо сопровождаемый продукт.
                У меня получилось норм, что-то из моего кода портировали на другие железки. Повозиться мне, конечно, пришлось, и я не верил в смысл всего этого дела, но теперь вижу, что смысл есть. Если делать хорошо. И не по требованиям ГОСТ… Кстати, в ГОСТ написаны обязательные разделы, но никто не мешает вводить свои разделы. И писать туда что угодно.
                  0
                  По-хорошему, ГОСТ требует описания основополагающих принципов программы. Концепцию и обобщённый алгоритм. Диаграмму классов/объектов (с полями, методами, взаимосвязями). Описание структур данных. Описание состава и назначения программных модулей и их API. Структуру программы (службы, процедуры, и данные, входящие в программу и взаимосвязи между ними). Блок-схемы алгоритмов сложных функций или процессов. А также текстовое описание всего этого дела. Если всё это сделать, то получится очень даже неплохо. Я в обычных проектах не видел такого, если честно. Там обычно не ясна концепция продукта. Т.к. хорошая программа — это некоторая объектная модель, которую можно визуализировать в виде диаграммы классов и объектной диаграммы. Вот эту объектную модель в визуальном виде я нигде пока не встречал (правда я открытые проекты почти не копал).
                    0
                    Вы программу рассматриваете как что-то статическое и неизменное?
                    Ок. Вот допустим вы решили сделать рефакторинг, придется переписывать всю гостовскую часть с нуля?
                      0
                      А что поменяется в результате рефакторинга? Код отдельно взятой функции оптимизируется? Всякую мелочёвку не обязательно разрисовывать в виде блок-схем. Изменится объектная модель, появятся новые процессы, изменятся данные, которые обрабатываются процессами — да, это будет нужно отразить в документации. Но почему с нуля? Если у Вас программа представляет собой «портянку» из одной функции, которая разрисована в виде блок-схемы и описана текстом в виде последовательности операторов, тогда придётся переписывать с нуля. Если у Вас модульная программа, то нужно будет поправить описание одного модуля. Это — неизбежная плата за переносимость. Опять же, технические писатели на это есть.
                      К примеру, если у Вас есть функция… Эммм… Скажем, преобразования Фурье некоторого семпла данных. И Вы хотите провести рефакторинг. Вы можете описать эту функцию просто: данная подпрограмма выполняет быстрое прямое преобразование Фурье. Использует следующие переменные: указатель на структуру данных, число записей, период сигнала. Результатом преобразования является указатель на структуру данных, содержащую действительные и мнимые части образов Фурье гармоник входного сигнала. Блок схема функции не приводится ввиду её простоты. В тексте подпрограммы приведены соответствующие комментарии. После рефакторинга Вам ничего не нужно переписывать в этом описании.
                    0
                    В путевых компаниях есть подразделение технических писателей для подготовки документации и аналитиков/архитекторов для подготовки ТЗ. Для open source проектов таких не держут. Посмотрел бы я на документацию к коду в произвольной форме на десяток АЭС или конвейерные линии. Да даже интересно было бы взглянуть на «заметки на полях» на наши госуслуги с их сопряжением с кучей других инф систем.
                  0
                  На мой взгляд, идеальная ситуация, когда в команде программистов есть технический писатель, который подчиняется руководителю разработки. Этот технический писатель имеет познания в программировании, и сидит на каждом код-ревью. В части структуры всего документа он консультируется с руководителем разработки, в части описания модулей руководствуется тем, что услышал на код-ревью, а также консультируется с разработчиками. Оформление документа по какому-либо стандарту лежит полностью на нём. Таким образом, общая канва документа будет задаваться стратегами и тактиками разработки, при этом они будут освобождены от возни со стандартами оформления и набором текста, подбором формулировок и т.п. Я своё описание рисовал и писал сам. Времени ушло едва ли не больше, чем на написание кода (при условии, что ГОСТы мне близки). Сначала я психовал, но сейчас я уже больше года работаю в другом отделе, а мой код живёт и развивается другими разработчиками. Т.е. вроде бы затраты окупились, программа превратилась почти в продукт.
                    0
                    Смысл Гостов в чем? Все проекты с которыми я работал великолепно документированы прямо в коде и по этому коду сгенерирована документация с развернутыми примерами. Это позволяет сделать поменяв к примеру функцию или ее параметры получить в один клик новую актуальную версию документации.

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

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

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

                      Вопрос к тем, кому приходилось писать такую проектную документацию. Какое ПО вы использовали?

                        +1
                        Исключительно Word. Ни разу не видел чтобы кто-то что-то иное использовал.
                          +1

                          Word, на мой взгляд, не очень хорошо работает с объемными колонтитулами (а рамка обычно в них).
                          А так, сам пишу в Word'е.
                          Знаю, что некоторые люди используют (La)TeX для этого. Там есть специальные библиотеки для ЕСКД.
                          В Компас'е есть опция "Текстовый документ", но в той версии с которой я работал функционал был крайне скуден.

                          0
                          Word с корпоративными надстройками и макросами.
                          0
                          Я оформляю документацию на автоматизированную систему с использованием markup'а в простых случаях. Если документация сложная и требует интеграции с кодом, то я использую Sphinx.

                          Если речь идёт про API, то swagger — отличное средство для самодокументирования приложения.

                          Последняя линяя «документной защиты» — это debian/changelog и git log.

                          А зачем мне ГОСТ? Какая от него польза заказчику? Исполнителю?
                            0
                            Ну в рамочках точно смысла нет.
                            А вот для ТЗ, допустим, требования ГОСТа вполне разумны. Ну, если относиться к нему как к чек-листу, который потом может не один раз выручить. Даже смешные «требования к упаковке и маркировке», в которых написано, что продукт передается заказчику в электронном виде по сети «интернет» может выручить, когда прибежит бухгалтерия заказчика и начнёт орать про «предоставьте нам коробку компакт-дисков, а то нам инвентарный номер ставить некуда». Или вот «методика приёмо-сдаточных испытаний» вполне себе сборник юзер-сторий, причём элементарно проверяемых.
                            +1
                            Плотно использовал в работе на протяжении 10+ лет.
                            У меня за все время сложилось такое твердое убеждение — сильно противятся ГОСТам в работе либо те, кто их читать не умеет, либо очень уж творческие натуры.
                            И вот, кстати, на счет того, как правильно читать эти документы, в интернете статей что-то нет совсем. Неподготовленного человека сухой текст стандарта повергает в уныние. А ведь там каждое слово взвешено — в старых, еще советских ГОСТах.
                            Я как-то читал современную версию стандартов — уж не помню, что за стандарт был — какие-то «размышления на тему», а не стандарт.
                              0
                              Сходу поразило: "Одним пятничным вечером… получил задание от руководителя подготовить за выходные ТЗ". Да пусть меня побьют работодатели, но с годами (к сожалению, поздно) понял, что это, за редким исключением:
                              а) профнепригодность руководителя (а это мы видим уже итог — неуважение к сотруднику);
                              б) неуважение сотрудника к самому себе (что перерастает в профнепригодность сотрудника).
                              Не, ну если садо встретилось с мазо — флаг в руки.

                              По сути. То или иное применение ГОСТов зависит от цели документации.
                              Если это обязаловка, то тут задача ПМ и техписа очень-очень грамотно подойти к формулированию структуры будущей документации до заключения договора/ТЗ и далее жёстко контролировать соответствие требований всех заинтересованных сторон к документации согласно вот тем самым сформулированным договорённостям, которые эти заинтересованные стороны подписали. Иначе полноценная, нормальная работа выльется в кошмар для всех сторон.
                              Если «для дома, для семьи», то в голове должна быть элементарная цель — документация должна быть такой, чтобы спец вашего уровня (а желательно, ступенькой ниже) понял её, точнее, описываемую систему. Тут ГОСТы должны служит опорой. Причина проста — в них аккумулирована общепринятая логика, которая с вероятностью 99.(9)% будет лучше вашей наколеночной.
                              Конечно, есть проблемы, тут в комментах уже обозначили. ГОСТ — это не 100% догма. Надо понять суть (логику) стандартов, в т.ч. их рамки. Это, да, требует времени и работу мысли :), а ещё и памяти (если плотно не применять, у меня быстро улетучивается, поэтому всегда работаю с постоянным обращениям к стандартам). Далее, надо сопоставить цель документации со стандартами, выработать оптимальную структуру и согласовать (см. выше). Всё, готово, можно наполнять содержанием и контролировать (через ПМ, инженеров etc) как идёт проект.

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

                              Самое читаемое