Так выглядит памятка и вот ссылка для скачивания, распечатки и вывешивания на почетное место.
Для вашего удобства собрал ссылки на приведенные документы. В принципе этого будет достаточно, чтобы удовлетворить запросы самого требовательного заказчика. Некоторым из этих стандартов скоро исполнится 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) Единая система программной документации
Расскажите, насколько часто вам приходится иметь дело с ГОСТами этой серии и насколько удается применять эти рекомендации в процессе составления документации. А ниже — небольшой опрос. Заранее большое спасибо за обратную связь!
Автор статьи: Антон Касимов, архитектор систем управления.
Только зарегистрированные пользователи могут участвовать в опросе. Войдите, пожалуйста.
Комментарии (20)
beduin01
17.02.2017 11:08+2Искренне сочувствую всем тем кому по этой херне приходится работать. К сожалению результатами Гостофикации ИТ можно только подтереться. За примерами ходить далеко не надо. Можно любую документацию по любому продукту выполненную по ГОСТу посмотреть.
RegisterWindowClassExA
17.02.2017 11:43Ну, если подойти к делу творчески, то получается вполне неплохо. Я бы даже сказал, что это стоит потраченного времени. Но только после написания кода. Например, я свой код очень легко передал коллеге, т.к. у меня было вменяемое описание программы, её назначения, структуры, модулей и их API, и даже алгоритмы были разрисованы. Другое дело, что заниматься этим следует не программисту, а техническому писателю. Я сейчас для рисования блок-схем нанимаю фрилансеров. В принципе, ничего страшного ГОСТ на ИТ не требует — руководства программиста, руководство оператора, и прочее. Но для его использования ГОСТ нужно, по-сути, переписывать на ходу, подгоняя под современные реалии, т.к. многое писалось ещё с оглядкой на ЕС ЭВМ, не под GUI, там у них какие-то сообщения постоянно, команды и прочие консольные реалии. Для описания консольных утилит вполне подойдёт. Если у Вас GUI и ООП — тогда нужно творчески переосмысливать, придумывать на ходу. Это можно делать — ГОСТ устарел, значит он сам виноват.
mklochkov
17.02.2017 15:26+1ГОСТ-ы следует применять творчески, сообразно с обстоятельствами. А для того чтобы уверенно это делать — нужно представлять, что в них написано. Возьмём документ 34.601-90, он самый короткий из перечисленных.
Что плохого в том, что он требует написания концепции? Да ничего плохого в этом нет, наоборот хорошо. Даже для маленького сайта, разрабатываемого стартапом из трёх человек — соберитесь в кафе, договоритесь между собой, напишите на салфетке, что сайт должен делать то-то для тех-то, писать мы его будем, условно, на python+django, размещать на хостинге с использованием контейнерной виртуализации. Назовите этот документ концепцией, и дальше ей следуйте. Это убережёт от массы лишних движений и потенциальных переделок.
И будет у вас документация (сюрприз!) — в точном соответствии с ГОСТ-ом, но в объеме, потребном именно для этого небольшого проекта. Вырастет проект — на определённом этапе его доработки придёте к необходимости ТЗ. Опять же, не надо писать все разделы — напишите только нужные. ГОСТ 34.602-89 это явно разрешает.
RegisterWindowClassExA
17.02.2017 11:37+2По работе приходится использовать ГОСТы. Приходилось оформлять по ним и схемы, и текстовые документы — инструкции, эксплуатационные документы. Когда стал заниматься программированием, приходилось заниматься и оформлением программной документации по ЕСПД.
Общее впечатление от этого дела — нужная штука там, где необходима поддержка продукта. Т.е. если жизненный цикл продукта будет дольше, чем время работы специалиста на предприятии, то нужно оформлять документацию по какому-либо стандарту. Именно ГОСТ, наверное, не обязательно, но некоторый стандарт должен быть. Опять же, зависит от изделия. Если Вы делаете сложный продукт или продукт для массового производства — тогда необходимо. Если Вы делаете что-то для кустарного производства, то не обязательно строго следовать стандартам, достаточно заметок «на полях». Если программа или продукт — это что-то простое, тогда документация вообще не нужна — быстрее его реверснуть в уме или перепроектировать, нежели копаться в документации.
В целом, ГОСТы во много устарели. В частности, ЕСПД требует разработку алгоритмов до написания программы. Ф. Брукс осуждает такой подход (он, видимо, списан с ИСО-шных гостов), говорит, что блок-схемы вообще не нужны. ГОСТ не предусматривает диаграмм классов, и прочего. Только блок-схемы, имеющие смысл лишь для процедурной парадигмы. Если у Вас ООП, то приходится изобретать.
Плюсы применения ГОСТов появляются лишь тогда, когда продукт живёт долго. Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт. Минус ГОСТов — время на разработоку документации по стандарту (и время на внедрение стандарта).
ГОСТы часто приходится применять и усовершенствовать с оглядкой на современные технологии. Запилить диаграмму классов в ГОСТовской рамке — вот Вам и новый программный документ. Хотя все диаграммы идут в составе инструкций программиста и описаний. Просто для них не предусмотрены обозначения. Придумываете сами (или заимствуете у иностранцев). ГОСТ это позволяет делать, если в самом ГОСТе нет обозначений.
В целом, ГОСТ вполне себе неплох. Современные САПР позволяют лепить КД в ГОСТе, прямо в процессе построения схем, эмуляции и построении трёхмерных моделей. С технологией производства это тоже сопрягут со временем, т.е. можно будет по модели листового тела получить и чертёж, программу для лазерного станка, и т.п.
По сути, КД и ПД — это продукт. И только владельцу предприятия решать, какой продукт должно производить его предприятие — отгружаемый заказчику или бумажный. И распределять усилия сотрудников.
Да, самое главное — на большинстве предприятий для оформления текстовых документов держат специальных технических писателей. Для оформления чертежей раньше были чертёжники, которые работали на инженеров. С развитием САПР стало считаться, что конструктор сам в состоянии справится с оформлением КД.beduin01
17.02.2017 11:42>Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт.
Категорически не согласен. Если бы разработка реальных продуктов шла по гостам никто бы вообще ни во что не врубался. Гост это сугубо формальный подход т.е. когда пишут не то что нужно, а то что требует Гост.
За примерами ходить далеко не надо — откройте любой большой проект на github который развивается 5-7 лет и посмотрите как там разработка устроена и документирование.
RegisterWindowClassExA
17.02.2017 11:51Ну, всё зависит от того, кто пишет документацию. Если пишется для того, чтобы отвязались, тогда документация получается такая, как Вы пишете. Если пишут на совесть, то получается хорошо сопровождаемый продукт.
У меня получилось норм, что-то из моего кода портировали на другие железки. Повозиться мне, конечно, пришлось, и я не верил в смысл всего этого дела, но теперь вижу, что смысл есть. Если делать хорошо. И не по требованиям ГОСТ… Кстати, в ГОСТ написаны обязательные разделы, но никто не мешает вводить свои разделы. И писать туда что угодно.
RegisterWindowClassExA
17.02.2017 11:57По-хорошему, ГОСТ требует описания основополагающих принципов программы. Концепцию и обобщённый алгоритм. Диаграмму классов/объектов (с полями, методами, взаимосвязями). Описание структур данных. Описание состава и назначения программных модулей и их API. Структуру программы (службы, процедуры, и данные, входящие в программу и взаимосвязи между ними). Блок-схемы алгоритмов сложных функций или процессов. А также текстовое описание всего этого дела. Если всё это сделать, то получится очень даже неплохо. Я в обычных проектах не видел такого, если честно. Там обычно не ясна концепция продукта. Т.к. хорошая программа — это некоторая объектная модель, которую можно визуализировать в виде диаграммы классов и объектной диаграммы. Вот эту объектную модель в визуальном виде я нигде пока не встречал (правда я открытые проекты почти не копал).
beduin01
17.02.2017 12:05Вы программу рассматриваете как что-то статическое и неизменное?
Ок. Вот допустим вы решили сделать рефакторинг, придется переписывать всю гостовскую часть с нуля?RegisterWindowClassExA
17.02.2017 12:32А что поменяется в результате рефакторинга? Код отдельно взятой функции оптимизируется? Всякую мелочёвку не обязательно разрисовывать в виде блок-схем. Изменится объектная модель, появятся новые процессы, изменятся данные, которые обрабатываются процессами — да, это будет нужно отразить в документации. Но почему с нуля? Если у Вас программа представляет собой «портянку» из одной функции, которая разрисована в виде блок-схемы и описана текстом в виде последовательности операторов, тогда придётся переписывать с нуля. Если у Вас модульная программа, то нужно будет поправить описание одного модуля. Это — неизбежная плата за переносимость. Опять же, технические писатели на это есть.
К примеру, если у Вас есть функция… Эммм… Скажем, преобразования Фурье некоторого семпла данных. И Вы хотите провести рефакторинг. Вы можете описать эту функцию просто: данная подпрограмма выполняет быстрое прямое преобразование Фурье. Использует следующие переменные: указатель на структуру данных, число записей, период сигнала. Результатом преобразования является указатель на структуру данных, содержащую действительные и мнимые части образов Фурье гармоник входного сигнала. Блок схема функции не приводится ввиду её простоты. В тексте подпрограммы приведены соответствующие комментарии. После рефакторинга Вам ничего не нужно переписывать в этом описании.
RegisterWindowClassExA
17.02.2017 12:22На мой взгляд, идеальная ситуация, когда в команде программистов есть технический писатель, который подчиняется руководителю разработки. Этот технический писатель имеет познания в программировании, и сидит на каждом код-ревью. В части структуры всего документа он консультируется с руководителем разработки, в части описания модулей руководствуется тем, что услышал на код-ревью, а также консультируется с разработчиками. Оформление документа по какому-либо стандарту лежит полностью на нём. Таким образом, общая канва документа будет задаваться стратегами и тактиками разработки, при этом они будут освобождены от возни со стандартами оформления и набором текста, подбором формулировок и т.п. Я своё описание рисовал и писал сам. Времени ушло едва ли не больше, чем на написание кода (при условии, что ГОСТы мне близки). Сначала я психовал, но сейчас я уже больше года работаю в другом отделе, а мой код живёт и развивается другими разработчиками. Т.е. вроде бы затраты окупились, программа превратилась почти в продукт.
beduin01
17.02.2017 14:03Смысл Гостов в чем? Все проекты с которыми я работал великолепно документированы прямо в коде и по этому коду сгенерирована документация с развернутыми примерами. Это позволяет сделать поменяв к примеру функцию или ее параметры получить в один клик новую актуальную версию документации.
Т.е. все решение у разработчика как на ладони. Он видит какие функции, методы и переменные есть в коде. Может автоматом перейти на нужные участки кода и тд. Тут же предлагается какой-то суррогат делать за актуальностью которого нужно отдельно следить.
Я просто сам с гостами много работал и для себя понял их абсолютную бестолковость. В них даже терминологию нельзя адекватную использовать и приходится слова которые запутают любого адекватного разработчика использовать.
50kiloofcabbage
17.02.2017 15:56ГОСТ это для глупых и ленивых, которые не способны сами выработать правильные и полезные требования к документации.
ГОСТы — зло, но лучше у нас ничего не придумали и придумывать не хотят, и не будут. Особенно для АСУ.
Bahuser
17.02.2017 15:56Вопрос к тем, кому приходилось писать такую проектную документацию. Какое ПО вы использовали?
beduin01
17.02.2017 17:09+1Исключительно Word. Ни разу не видел чтобы кто-то что-то иное использовал.
Bahuser
17.02.2017 20:33+1Word, на мой взгляд, не очень хорошо работает с объемными колонтитулами (а рамка обычно в них).
А так, сам пишу в Word'е.
Знаю, что некоторые люди используют (La)TeX для этого. Там есть специальные библиотеки для ЕСКД.
В Компас'е есть опция "Текстовый документ", но в той версии с которой я работал функционал был крайне скуден.
amarao
17.02.2017 17:52Я оформляю документацию на автоматизированную систему с использованием markup'а в простых случаях. Если документация сложная и требует интеграции с кодом, то я использую Sphinx.
Если речь идёт про API, то swagger — отличное средство для самодокументирования приложения.
Последняя линяя «документной защиты» — это debian/changelog и git log.
А зачем мне ГОСТ? Какая от него польза заказчику? Исполнителю?
vanxant
18.02.2017 06:10Ну в рамочках точно смысла нет.
А вот для ТЗ, допустим, требования ГОСТа вполне разумны. Ну, если относиться к нему как к чек-листу, который потом может не один раз выручить. Даже смешные «требования к упаковке и маркировке», в которых написано, что продукт передается заказчику в электронном виде по сети «интернет» может выручить, когда прибежит бухгалтерия заказчика и начнёт орать про «предоставьте нам коробку компакт-дисков, а то нам инвентарный номер ставить некуда». Или вот «методика приёмо-сдаточных испытаний» вполне себе сборник юзер-сторий, причём элементарно проверяемых.
throttle
17.02.2017 18:13+1Плотно использовал в работе на протяжении 10+ лет.
У меня за все время сложилось такое твердое убеждение — сильно противятся ГОСТам в работе либо те, кто их читать не умеет, либо очень уж творческие натуры.
И вот, кстати, на счет того, как правильно читать эти документы, в интернете статей что-то нет совсем. Неподготовленного человека сухой текст стандарта повергает в уныние. А ведь там каждое слово взвешено — в старых, еще советских ГОСТах.
Я как-то читал современную версию стандартов — уж не помню, что за стандарт был — какие-то «размышления на тему», а не стандарт.
MgmZog
А страшные шрифты для рамки разве не прописаны в ГОСТе?
ITSystemsManagement
Эти леденящие кровь вещи можно найти в ЕСКД (ГОСТ 2)