Comments 23
А страшные шрифты для рамки разве не прописаны в ГОСТе?
Искренне сочувствую всем тем кому по этой херне приходится работать. К сожалению результатами Гостофикации ИТ можно только подтереться. За примерами ходить далеко не надо. Можно любую документацию по любому продукту выполненную по ГОСТу посмотреть.
Ну, если подойти к делу творчески, то получается вполне неплохо. Я бы даже сказал, что это стоит потраченного времени. Но только после написания кода. Например, я свой код очень легко передал коллеге, т.к. у меня было вменяемое описание программы, её назначения, структуры, модулей и их API, и даже алгоритмы были разрисованы. Другое дело, что заниматься этим следует не программисту, а техническому писателю. Я сейчас для рисования блок-схем нанимаю фрилансеров. В принципе, ничего страшного ГОСТ на ИТ не требует — руководства программиста, руководство оператора, и прочее. Но для его использования ГОСТ нужно, по-сути, переписывать на ходу, подгоняя под современные реалии, т.к. многое писалось ещё с оглядкой на ЕС ЭВМ, не под GUI, там у них какие-то сообщения постоянно, команды и прочие консольные реалии. Для описания консольных утилит вполне подойдёт. Если у Вас GUI и ООП — тогда нужно творчески переосмысливать, придумывать на ходу. Это можно делать — ГОСТ устарел, значит он сам виноват.
ГОСТ-ы следует применять творчески, сообразно с обстоятельствами. А для того чтобы уверенно это делать — нужно представлять, что в них написано. Возьмём документ 34.601-90, он самый короткий из перечисленных.
Что плохого в том, что он требует написания концепции? Да ничего плохого в этом нет, наоборот хорошо. Даже для маленького сайта, разрабатываемого стартапом из трёх человек — соберитесь в кафе, договоритесь между собой, напишите на салфетке, что сайт должен делать то-то для тех-то, писать мы его будем, условно, на python+django, размещать на хостинге с использованием контейнерной виртуализации. Назовите этот документ концепцией, и дальше ей следуйте. Это убережёт от массы лишних движений и потенциальных переделок.
И будет у вас документация (сюрприз!) — в точном соответствии с ГОСТ-ом, но в объеме, потребном именно для этого небольшого проекта. Вырастет проект — на определённом этапе его доработки придёте к необходимости ТЗ. Опять же, не надо писать все разделы — напишите только нужные. ГОСТ 34.602-89 это явно разрешает.
Что плохого в том, что он требует написания концепции? Да ничего плохого в этом нет, наоборот хорошо. Даже для маленького сайта, разрабатываемого стартапом из трёх человек — соберитесь в кафе, договоритесь между собой, напишите на салфетке, что сайт должен делать то-то для тех-то, писать мы его будем, условно, на python+django, размещать на хостинге с использованием контейнерной виртуализации. Назовите этот документ концепцией, и дальше ей следуйте. Это убережёт от массы лишних движений и потенциальных переделок.
И будет у вас документация (сюрприз!) — в точном соответствии с ГОСТ-ом, но в объеме, потребном именно для этого небольшого проекта. Вырастет проект — на определённом этапе его доработки придёте к необходимости ТЗ. Опять же, не надо писать все разделы — напишите только нужные. ГОСТ 34.602-89 это явно разрешает.
По работе приходится использовать ГОСТы. Приходилось оформлять по ним и схемы, и текстовые документы — инструкции, эксплуатационные документы. Когда стал заниматься программированием, приходилось заниматься и оформлением программной документации по ЕСПД.
Общее впечатление от этого дела — нужная штука там, где необходима поддержка продукта. Т.е. если жизненный цикл продукта будет дольше, чем время работы специалиста на предприятии, то нужно оформлять документацию по какому-либо стандарту. Именно ГОСТ, наверное, не обязательно, но некоторый стандарт должен быть. Опять же, зависит от изделия. Если Вы делаете сложный продукт или продукт для массового производства — тогда необходимо. Если Вы делаете что-то для кустарного производства, то не обязательно строго следовать стандартам, достаточно заметок «на полях». Если программа или продукт — это что-то простое, тогда документация вообще не нужна — быстрее его реверснуть в уме или перепроектировать, нежели копаться в документации.
В целом, ГОСТы во много устарели. В частности, ЕСПД требует разработку алгоритмов до написания программы. Ф. Брукс осуждает такой подход (он, видимо, списан с ИСО-шных гостов), говорит, что блок-схемы вообще не нужны. ГОСТ не предусматривает диаграмм классов, и прочего. Только блок-схемы, имеющие смысл лишь для процедурной парадигмы. Если у Вас ООП, то приходится изобретать.
Плюсы применения ГОСТов появляются лишь тогда, когда продукт живёт долго. Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт. Минус ГОСТов — время на разработоку документации по стандарту (и время на внедрение стандарта).
ГОСТы часто приходится применять и усовершенствовать с оглядкой на современные технологии. Запилить диаграмму классов в ГОСТовской рамке — вот Вам и новый программный документ. Хотя все диаграммы идут в составе инструкций программиста и описаний. Просто для них не предусмотрены обозначения. Придумываете сами (или заимствуете у иностранцев). ГОСТ это позволяет делать, если в самом ГОСТе нет обозначений.
В целом, ГОСТ вполне себе неплох. Современные САПР позволяют лепить КД в ГОСТе, прямо в процессе построения схем, эмуляции и построении трёхмерных моделей. С технологией производства это тоже сопрягут со временем, т.е. можно будет по модели листового тела получить и чертёж, программу для лазерного станка, и т.п.
По сути, КД и ПД — это продукт. И только владельцу предприятия решать, какой продукт должно производить его предприятие — отгружаемый заказчику или бумажный. И распределять усилия сотрудников.
Да, самое главное — на большинстве предприятий для оформления текстовых документов держат специальных технических писателей. Для оформления чертежей раньше были чертёжники, которые работали на инженеров. С развитием САПР стало считаться, что конструктор сам в состоянии справится с оформлением КД.
Общее впечатление от этого дела — нужная штука там, где необходима поддержка продукта. Т.е. если жизненный цикл продукта будет дольше, чем время работы специалиста на предприятии, то нужно оформлять документацию по какому-либо стандарту. Именно ГОСТ, наверное, не обязательно, но некоторый стандарт должен быть. Опять же, зависит от изделия. Если Вы делаете сложный продукт или продукт для массового производства — тогда необходимо. Если Вы делаете что-то для кустарного производства, то не обязательно строго следовать стандартам, достаточно заметок «на полях». Если программа или продукт — это что-то простое, тогда документация вообще не нужна — быстрее его реверснуть в уме или перепроектировать, нежели копаться в документации.
В целом, ГОСТы во много устарели. В частности, ЕСПД требует разработку алгоритмов до написания программы. Ф. Брукс осуждает такой подход (он, видимо, списан с ИСО-шных гостов), говорит, что блок-схемы вообще не нужны. ГОСТ не предусматривает диаграмм классов, и прочего. Только блок-схемы, имеющие смысл лишь для процедурной парадигмы. Если у Вас ООП, то приходится изобретать.
Плюсы применения ГОСТов появляются лишь тогда, когда продукт живёт долго. Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт. Минус ГОСТов — время на разработоку документации по стандарту (и время на внедрение стандарта).
ГОСТы часто приходится применять и усовершенствовать с оглядкой на современные технологии. Запилить диаграмму классов в ГОСТовской рамке — вот Вам и новый программный документ. Хотя все диаграммы идут в составе инструкций программиста и описаний. Просто для них не предусмотрены обозначения. Придумываете сами (или заимствуете у иностранцев). ГОСТ это позволяет делать, если в самом ГОСТе нет обозначений.
В целом, ГОСТ вполне себе неплох. Современные САПР позволяют лепить КД в ГОСТе, прямо в процессе построения схем, эмуляции и построении трёхмерных моделей. С технологией производства это тоже сопрягут со временем, т.е. можно будет по модели листового тела получить и чертёж, программу для лазерного станка, и т.п.
По сути, КД и ПД — это продукт. И только владельцу предприятия решать, какой продукт должно производить его предприятие — отгружаемый заказчику или бумажный. И распределять усилия сотрудников.
Да, самое главное — на большинстве предприятий для оформления текстовых документов держат специальных технических писателей. Для оформления чертежей раньше были чертёжники, которые работали на инженеров. С развитием САПР стало считаться, что конструктор сам в состоянии справится с оформлением КД.
>Старый разработчик ушёл, пришёл новый, ему дали папку с доками, он всё прочитал и врубился в продукт.
Категорически не согласен. Если бы разработка реальных продуктов шла по гостам никто бы вообще ни во что не врубался. Гост это сугубо формальный подход т.е. когда пишут не то что нужно, а то что требует Гост.
За примерами ходить далеко не надо — откройте любой большой проект на github который развивается 5-7 лет и посмотрите как там разработка устроена и документирование.
Категорически не согласен. Если бы разработка реальных продуктов шла по гостам никто бы вообще ни во что не врубался. Гост это сугубо формальный подход т.е. когда пишут не то что нужно, а то что требует Гост.
За примерами ходить далеко не надо — откройте любой большой проект на github который развивается 5-7 лет и посмотрите как там разработка устроена и документирование.
Ну, всё зависит от того, кто пишет документацию. Если пишется для того, чтобы отвязались, тогда документация получается такая, как Вы пишете. Если пишут на совесть, то получается хорошо сопровождаемый продукт.
У меня получилось норм, что-то из моего кода портировали на другие железки. Повозиться мне, конечно, пришлось, и я не верил в смысл всего этого дела, но теперь вижу, что смысл есть. Если делать хорошо. И не по требованиям ГОСТ… Кстати, в ГОСТ написаны обязательные разделы, но никто не мешает вводить свои разделы. И писать туда что угодно.
У меня получилось норм, что-то из моего кода портировали на другие железки. Повозиться мне, конечно, пришлось, и я не верил в смысл всего этого дела, но теперь вижу, что смысл есть. Если делать хорошо. И не по требованиям ГОСТ… Кстати, в ГОСТ написаны обязательные разделы, но никто не мешает вводить свои разделы. И писать туда что угодно.
По-хорошему, ГОСТ требует описания основополагающих принципов программы. Концепцию и обобщённый алгоритм. Диаграмму классов/объектов (с полями, методами, взаимосвязями). Описание структур данных. Описание состава и назначения программных модулей и их API. Структуру программы (службы, процедуры, и данные, входящие в программу и взаимосвязи между ними). Блок-схемы алгоритмов сложных функций или процессов. А также текстовое описание всего этого дела. Если всё это сделать, то получится очень даже неплохо. Я в обычных проектах не видел такого, если честно. Там обычно не ясна концепция продукта. Т.к. хорошая программа — это некоторая объектная модель, которую можно визуализировать в виде диаграммы классов и объектной диаграммы. Вот эту объектную модель в визуальном виде я нигде пока не встречал (правда я открытые проекты почти не копал).
Вы программу рассматриваете как что-то статическое и неизменное?
Ок. Вот допустим вы решили сделать рефакторинг, придется переписывать всю гостовскую часть с нуля?
Ок. Вот допустим вы решили сделать рефакторинг, придется переписывать всю гостовскую часть с нуля?
А что поменяется в результате рефакторинга? Код отдельно взятой функции оптимизируется? Всякую мелочёвку не обязательно разрисовывать в виде блок-схем. Изменится объектная модель, появятся новые процессы, изменятся данные, которые обрабатываются процессами — да, это будет нужно отразить в документации. Но почему с нуля? Если у Вас программа представляет собой «портянку» из одной функции, которая разрисована в виде блок-схемы и описана текстом в виде последовательности операторов, тогда придётся переписывать с нуля. Если у Вас модульная программа, то нужно будет поправить описание одного модуля. Это — неизбежная плата за переносимость. Опять же, технические писатели на это есть.
К примеру, если у Вас есть функция… Эммм… Скажем, преобразования Фурье некоторого семпла данных. И Вы хотите провести рефакторинг. Вы можете описать эту функцию просто: данная подпрограмма выполняет быстрое прямое преобразование Фурье. Использует следующие переменные: указатель на структуру данных, число записей, период сигнала. Результатом преобразования является указатель на структуру данных, содержащую действительные и мнимые части образов Фурье гармоник входного сигнала. Блок схема функции не приводится ввиду её простоты. В тексте подпрограммы приведены соответствующие комментарии. После рефакторинга Вам ничего не нужно переписывать в этом описании.
К примеру, если у Вас есть функция… Эммм… Скажем, преобразования Фурье некоторого семпла данных. И Вы хотите провести рефакторинг. Вы можете описать эту функцию просто: данная подпрограмма выполняет быстрое прямое преобразование Фурье. Использует следующие переменные: указатель на структуру данных, число записей, период сигнала. Результатом преобразования является указатель на структуру данных, содержащую действительные и мнимые части образов Фурье гармоник входного сигнала. Блок схема функции не приводится ввиду её простоты. В тексте подпрограммы приведены соответствующие комментарии. После рефакторинга Вам ничего не нужно переписывать в этом описании.
В путевых компаниях есть подразделение технических писателей для подготовки документации и аналитиков/архитекторов для подготовки ТЗ. Для open source проектов таких не держут. Посмотрел бы я на документацию к коду в произвольной форме на десяток АЭС или конвейерные линии. Да даже интересно было бы взглянуть на «заметки на полях» на наши госуслуги с их сопряжением с кучей других инф систем.
На мой взгляд, идеальная ситуация, когда в команде программистов есть технический писатель, который подчиняется руководителю разработки. Этот технический писатель имеет познания в программировании, и сидит на каждом код-ревью. В части структуры всего документа он консультируется с руководителем разработки, в части описания модулей руководствуется тем, что услышал на код-ревью, а также консультируется с разработчиками. Оформление документа по какому-либо стандарту лежит полностью на нём. Таким образом, общая канва документа будет задаваться стратегами и тактиками разработки, при этом они будут освобождены от возни со стандартами оформления и набором текста, подбором формулировок и т.п. Я своё описание рисовал и писал сам. Времени ушло едва ли не больше, чем на написание кода (при условии, что ГОСТы мне близки). Сначала я психовал, но сейчас я уже больше года работаю в другом отделе, а мой код живёт и развивается другими разработчиками. Т.е. вроде бы затраты окупились, программа превратилась почти в продукт.
Смысл Гостов в чем? Все проекты с которыми я работал великолепно документированы прямо в коде и по этому коду сгенерирована документация с развернутыми примерами. Это позволяет сделать поменяв к примеру функцию или ее параметры получить в один клик новую актуальную версию документации.
Т.е. все решение у разработчика как на ладони. Он видит какие функции, методы и переменные есть в коде. Может автоматом перейти на нужные участки кода и тд. Тут же предлагается какой-то суррогат делать за актуальностью которого нужно отдельно следить.
Я просто сам с гостами много работал и для себя понял их абсолютную бестолковость. В них даже терминологию нельзя адекватную использовать и приходится слова которые запутают любого адекватного разработчика использовать.
Т.е. все решение у разработчика как на ладони. Он видит какие функции, методы и переменные есть в коде. Может автоматом перейти на нужные участки кода и тд. Тут же предлагается какой-то суррогат делать за актуальностью которого нужно отдельно следить.
Я просто сам с гостами много работал и для себя понял их абсолютную бестолковость. В них даже терминологию нельзя адекватную использовать и приходится слова которые запутают любого адекватного разработчика использовать.
ГОСТ это для глупых и ленивых, которые не способны сами выработать правильные и полезные требования к документации.
ГОСТы — зло, но лучше у нас ничего не придумали и придумывать не хотят, и не будут. Особенно для АСУ.
ГОСТы — зло, но лучше у нас ничего не придумали и придумывать не хотят, и не будут. Особенно для АСУ.
Вопрос к тем, кому приходилось писать такую проектную документацию. Какое ПО вы использовали?
Исключительно Word. Ни разу не видел чтобы кто-то что-то иное использовал.
Word, на мой взгляд, не очень хорошо работает с объемными колонтитулами (а рамка обычно в них).
А так, сам пишу в Word'е.
Знаю, что некоторые люди используют (La)TeX для этого. Там есть специальные библиотеки для ЕСКД.
В Компас'е есть опция "Текстовый документ", но в той версии с которой я работал функционал был крайне скуден.
Word с корпоративными надстройками и макросами.
Я оформляю документацию на автоматизированную систему с использованием markup'а в простых случаях. Если документация сложная и требует интеграции с кодом, то я использую Sphinx.
Если речь идёт про API, то swagger — отличное средство для самодокументирования приложения.
Последняя линяя «документной защиты» — это debian/changelog и git log.
А зачем мне ГОСТ? Какая от него польза заказчику? Исполнителю?
Если речь идёт про API, то swagger — отличное средство для самодокументирования приложения.
Последняя линяя «документной защиты» — это debian/changelog и git log.
А зачем мне ГОСТ? Какая от него польза заказчику? Исполнителю?
Ну в рамочках точно смысла нет.
А вот для ТЗ, допустим, требования ГОСТа вполне разумны. Ну, если относиться к нему как к чек-листу, который потом может не один раз выручить. Даже смешные «требования к упаковке и маркировке», в которых написано, что продукт передается заказчику в электронном виде по сети «интернет» может выручить, когда прибежит бухгалтерия заказчика и начнёт орать про «предоставьте нам коробку компакт-дисков, а то нам инвентарный номер ставить некуда». Или вот «методика приёмо-сдаточных испытаний» вполне себе сборник юзер-сторий, причём элементарно проверяемых.
А вот для ТЗ, допустим, требования ГОСТа вполне разумны. Ну, если относиться к нему как к чек-листу, который потом может не один раз выручить. Даже смешные «требования к упаковке и маркировке», в которых написано, что продукт передается заказчику в электронном виде по сети «интернет» может выручить, когда прибежит бухгалтерия заказчика и начнёт орать про «предоставьте нам коробку компакт-дисков, а то нам инвентарный номер ставить некуда». Или вот «методика приёмо-сдаточных испытаний» вполне себе сборник юзер-сторий, причём элементарно проверяемых.
Плотно использовал в работе на протяжении 10+ лет.
У меня за все время сложилось такое твердое убеждение — сильно противятся ГОСТам в работе либо те, кто их читать не умеет, либо очень уж творческие натуры.
И вот, кстати, на счет того, как правильно читать эти документы, в интернете статей что-то нет совсем. Неподготовленного человека сухой текст стандарта повергает в уныние. А ведь там каждое слово взвешено — в старых, еще советских ГОСТах.
Я как-то читал современную версию стандартов — уж не помню, что за стандарт был — какие-то «размышления на тему», а не стандарт.
У меня за все время сложилось такое твердое убеждение — сильно противятся ГОСТам в работе либо те, кто их читать не умеет, либо очень уж творческие натуры.
И вот, кстати, на счет того, как правильно читать эти документы, в интернете статей что-то нет совсем. Неподготовленного человека сухой текст стандарта повергает в уныние. А ведь там каждое слово взвешено — в старых, еще советских ГОСТах.
Я как-то читал современную версию стандартов — уж не помню, что за стандарт был — какие-то «размышления на тему», а не стандарт.
UFO just landed and posted this here
Sign up to leave a comment.
Удобная памятка и 8 ссылок на документацию по ГОСТ 34 (автоматизированные системы)