Пример Руководство Программиста Гост
Сегодня мы поговорим об отечественных стандартах на проектную документацию. Как эти стандарты работают на практике, чем они плохи и чем хороши. При разработке документации для государственных и серьезных частных заказчиков у нас обычно нет выбора — в требования по документированию ТЗ вписано соблюдение стандартов. На практике мне приходилось сталкиваться с различными примерами недопонимания структуры стандартов, того, что должно быть в документах и зачем эти документы нужны.
В итоге из-под пера техписателей, аналитиков и специалистов выходят порой такие перлы, что непонятно, в каком состоянии сознания они писались. А ведь на самом деле все достаточно просто. Поиск по Хабру не вернул ссылок на более-менее целостный материал на данную тему, потому предлагаю закрасить этот досадный пробел. Что такое стандарты на документацию? В серии 34, о которой идет речь, существует всего 3 основных стандарта по документированию: Самый любимый и популярный стандарт по разработке ТЗ.
Оформление программного документа «Руководство оператора» произведено по требованиям ЕСПД (ГОСТ 19.101-77 1), ГОСТ 19.103-77 2), ГОСТ. Nov 19, 2015 - Разработка руководства программиста по ГОСТ 19. Руководство программиста относится к эксплуатационно-технической Пример.
ОБЩИЕ ПОЛОЖЕНИЯ. Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78. Составление информационной части (аннотации и содержания) является обязательным. Руководство программиста должно содержать следующие разделы: • назначение и условия применения программ; • характеристика программы; • обращение к программе; • входные и выходные данные; • сообщения. В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.). *Переиздание (Ноябрь 1987 г.) с Изменением № 1, утвержденным в сентябре 1981 г (ИУС 11-81). Руководство программиста должно содержать следующие разделы. Быть приведены дополнительные материалы (примеры, иллюстрации, таблицы,.
Единственное, не стоит забывать, что он крепко связан с другими стандартами серии и если вы получили ТЗ, выполненное по данному стандарту, крайне желательно придерживаться и других стандартов, даже если об этом нет прямых требований. Хотя бы в плане общей идеологии (о которой ниже) Это базовый документ, в котором приводится полный перечень документации ГОСТ 34, рекомендации по кодированию документов, к каким стадиям проекта относятся документы (стадии описываются в ГОСТ 34.601-90), а также как их можно объединить между собой. Фактически, этот стандарт представляет собой большую таблицу с комментариями. Ее можно загнать в Excel для удобства использования.
Объемистый стандарт, с различной степенью детальности описывающий содержание проектных документов. В качестве индекса используется упомянутый выше ГОСТ 34.201-89. К стандарту РД 50-34.698-90 существует множество вопросов и трактовок его положений, которые ввиду их неконкретности, часто понимают по-разному заказчик и исполнитель или даже члены проектной команды.
Но ничего более конкретного у нас, к сожалению, нет. Рассмотрим теперь плюсы и минусы стандартов, начав традиционно с минусов. Минусы стандартов Основной минус всем очевиден — стандарты старые. В них заложено устаревшее представление об архитектуре автоматизированной системы.
Например:. приложения двухуровневые, состоящие из клиентской программы и сервера СУБД (никаких трех- и более «уровневых» приложений, никаких Weblogic или JBoss). структура таблиц базы данных, будучи описана, даст представление о логической модели данных (то, что между приложением и базой может находиться какой-нибудь Hibernate, тогда казалось нехорошим излишеством). пользовательский интерфейс однооконный (а разве бывает другой? А что такое «браузер»?).
Отчетов в системе немного, все они бумажные и печатаются на матричном принтере. Разрабатываемая программа ориентирована на решение «задачи обработки информации», которая имеет четкий вход и выход и узко специализирована.
Feb 17, 2010 - Должностная инструкция инженера ПТО, должностные обязанности. Служебные поручения своего непосредственного начальника. Еткс начальник пто должностная инструкция.
В основе обработки информации лежит «алгоритм». Иногда «алгоритмов» бывает несколько. (Объектно-ориентированное программирование тогда делало лишь свои первые шаги и серьезно не рассматривалось). администратор базы данных понимает, какая информация лежит в таблицах и активно участвует в редактировании системных справочников (а разве бывает один сервер СУБД для 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 на стадии ТП. Дело в том, что стандарт предусматривает описание всего технического обеспечения, включая компьютерное «железо» и сети, инженерные системы и даже строительную часть (если потребуется).
А это хозяйство регламентируется громадным количеством стандартов и нормативных актов, согласуется в разных организациях и поэтому удобнее все дробить на части и согласовывать (править) по частям. В то же время стандарт позволяет объединять некоторые документы друг с другом, что имеет смысл делать, если всю кучу согласует один человек. Не забывайте также, что комплекс стандартов качества подразумевает учет и хранение технических документов, и наши «книжицы» у заказчика могут разойтись по разным архивам, в зависимости от предмета описания. Это еще один аргумент в пользу дробления документации.
Организационное обеспечение (ОО). Подавив в себе нормальное для технаря желание проскочить этот раздел поскорее, наоборот, рассмотрю его более подробно. Так как, коллеги, в последнее время на проектах наметились нехорошие тенденции, которые требуют внесения ясности именно в этот раздел.
На стадии ТП раздел содержит всего один документ « Описание организационной структуры», в котором мы должны рассказать заказчику, к чему он должен готовиться в плане изменения оргштатной структуры. Вдруг требуется организовать новый отдел для эксплуатации вашей системы, ввести новые должности и т.п. На стадии РД появляются другие, более интересные документы, которые мне бы хотелось рассмотреть отдельно. Руководство пользователя. Комментарии излишни, я думаю. Методика (технология) автоматизированного проектирования.
Тип, Бензиновый. Мощность, Вт, 5700. Мощность, Вт, 5700. Число фаз, 1. Класс, Средний. Выходное напряжение, В, 230. Тип запуска, ручной. Информация для правильной эксплуатации электростанции FUBAG. Сохраняйте данную инструкцию и обращайтесь к ней при возникновении вопросов. Занимающего около 1 минуты. Fubag(Фубаг) BS 6600 Бензиновая Электростанция, инструкция, поддержка, форум, описание, мануал, руководство, форум, Инструкция. 
Применяя правила описанные и перечисленные в данном руководстве по эксплуатации генератора Fubag BS 6600 A ES, вы можете быть уверенными. Operator's Manual Инструкция по эксплуатации. Power station. Электростанция бензиновая. BS 5500 A ES. BS 6600 A ES.
В этот документ при необходимости можно поместить описание процесса сборки ПО, управления версиями, тестирования и т.п. Но это если в ТЗ заказчик желает самолично осуществлять сборку ПО. Если он этого не требует (и не платит за это), то вся ваша внутренняя кухня не его ума дело, и этот документ делать не нужно. Технологическая инструкция.
В связи с модой на формализацию бизнес процессов, в этот документ ушлый заказчик иногда стремится запихнуть регламенты работы службы эксплуатации. Так вот, делать этого ни в коем случае не нужно. Описание бизнес-процессов, ролевые и должностные инструкции, регламенты работы — все это ОРД, то есть организационно-распорядительная документация. Которая является продуктом консалтингового проекта, который у вас, насколько я понимаю, не покупали. А покупали у вас проект технический и документацию к нему тоже техническую. Технологическая инструкция является прослойкой между ОРД и руководством пользователя. РП подробно описывает как нужно делать те или иные действия в системе.
Технологическая инструкция говорит о том, какие действия необходимо выполнять в тех или иных случаях, связанных с эксплуатацией системы. Грубо говоря, технологическая инструкция это краткий дайджест по РП для конкретной должности или роли. Если у заказчика роли не сформированы или он хочет, чтобы вы сами сформировали роли и требования к должностям, включите в документ самые базовые роли, например: оператор, старший оператор, администратор. Замечания заказчика на тему, «а у нас не так» или «а нам не нравится» должны сопровождаться перечнем ролей и описанием должностных обязанностей. Потому что бизнес-процессы мы не ставим.
Мы эти бизнес-процессы автоматизируем. Об описанных граблях я еще напишу отдельно, с красочными примерами, так как это повторяется уже не первый раз и в разных отраслях «народного хозяйства».
Описание технологического процесса обработки данных (включая телеобработку). Жалкий рудимент пещерного века, когда были специально выделенные «Операторы ЭВМ», скармливающие машине перфокарты и упаковывающие распечатку результата в конвертик. Эта инструкция — для них. Что в нее писать в XXI веке — я вам точно сказать не могу.
Выкручивайтесь сами. Самое лучшее, это просто забыть про этот документ. Общесистемные решения (ОР). Стандартом предусмотрено 17 документов раздела ОР.
Во-первых, это почти все документы предварительной фазы Эскизного проектирования. Во-вторых, это всевозможные сметы, расчеты и краткие описание автоматизируемых функций.
То есть, информация для людей не с основного ИТ-производства, а для вспомогательного персонала — менеджеров, сметчиков, специалистов по закупкам, экономистов и т.п. А в-третьих, в состав ОР входит мега-документ под названием «Пояснительная записка к техническому проекту», который по задумке представляет собой некий Executive Summary, а по факту многие проектанты пихают в него вообще все полезное содержание стадии ТП. Подобный радикальный подход бывает оправдан и даже взаимно выгоден и заказчику и исполнителю работ, но в определенных случаях.
Варианты использования ГОСТ 34. Полное и точное следование стандарту. Добровольно никто, естественно, такую тучу документов писать не будет. Поэтому полный комплект документов готовится только по настоятельной просьбе заказчика, которую он закрепил в ТЗ и еще договором сверху придавил. В таком случае требуется понимать все буквально и отдать заказчику физические «книжки», на которых будут стоять названия документов из таблицы 2 ГОСТ 34.201-89 за исключением совсем уж ненужных, перечень которых вы обязательно должны обговорить и закрепить письменно. Содержание документов также должно без всякой фантазии соответствовать РД 50-34.698-90, вплоть до названия разделов. Для того, чтобы у заказчика взорвался мозг, иногда большую систему делят на подсистемы, и для каждой подсистемы выпускают отдельную проектную документацию.
Выглядит это устрашающе и нормальному контролю при помощи земного разума не подлежит. Особенно в части интеграции подсистем. Что значительно упрощает приемку.
Главное, чтобы вы сами при этом не запутались и чтобы ваша система все-таки заработала как надо. Мы просто любим ГОСТы. В серьезных больших компаниях любят стандарты. Потому, что они помогают людям лучше понимать друг друга. Если ваш заказчик замечен в любви к порядку и стандартизации, постарайтесь придерживаться стандартной идеологии ГОСТ при разработке документов, даже если этого не требует ТЗ. Вас лучше поймут и одобрят согласующие специалисты, а вы сами не забудете включить в документацию важную информацию, лучше будете видеть целевую структуру документов, точнее планировать работы по их написанию и сэкономите себе и коллегам массу нервов и денег.
Нам плевать на документацию, лишь бы все работало. Исчезающий вид безответственного заказчика. Подобный взгляд на документацию пока еще можно встретить у небольших и бедных заказчиков, а также в оставшихся со времен перестройки авторитарных «идиотократиях», где босс окружен верными друзьями — директорами, и все вопросы решаются в личных беседах. Вы вольны в подобных условиях забивать на документирование вообще, но лучше, все таки, прицел не сбивать и хотя бы схематично наполнять содержимым документацию.
Руководство Программиста Гост Пример
Если не этому заказчику, так следующему передадите (продадите). Заключение Эта статья была о наших ГОСТах на документирование АСУ. ГОСТы старые, но, как оказалось, до сих пор очень даже полезные в хозяйстве. Не считая некоторые явные рудименты, структура документации обладает свойствами полноты и непротиворечивости, а следование стандарту снимает многие проектные риски, о существовании которых мы можем по началу не догадываться. Надеюсь, изложенный материал был вам полезен, или, как минимум, интересен. Несмотря на внешнюю скуку, документирование является важной и ответственной работой, аккуратность в которой так же важна, как и при написании хорошего кода.
Пишите хорошие документы, коллеги! А я на следующей неделе отправляюсь в две подряд командировки, так что публикацию новых материалов не гарантирую (загашника у меня нет, пишу из головы). Метки:. Добавить метки Пометьте публикацию своими метками Метки необходимо разделять запятой. Например: php, javascript, андронный коллайдер, задача трех тел. Да, свободный рынок как-то не очень работает. Я, например, ни разу не менял работу через агентство.
Все время по знакомству переводился. А теперь вообще командой кочуем. Несколько раз делал попытки собеседоваться через ХХ. Бесполезная трата времени. Кадровикам непонятно, за что мне вообще деньги платят. Так на любой работе, связанной с «высшими материями», где нужно не формальное соответствие, а адекватность. Проще всего принять на работу админа начального уровня.
Он только в дверь входит, а я уже знаю, подходит чувак или нет:). А вот с другими не так просто.
Попробую в двух словах дать выжимку своих ощущений от этой темы. (В идеале) должно быть удобно и понятно пользователю продукта. Иначе говоря, тут две переменных — продукт и его целевая аудитория. Неказистый (недостаточно хорошо спроектированный) продукт порождает сложную документацию. Не в последнюю очередь потому, что разработчики и сами не понимают, что представляет из себя этот продукт (к примеру, в вашем случае это может быть из-за недостаточно узкого определения продукта и недостаточно проработанных требований к нему; далее отсылаю к Алану Куперу). Клёвый продукт документировать легко, потому что целевая аудитория чётко определена.
Автору тогда не нужно писать все возможные варианты документации, потому что он не представляет, чего захочется людям. Простейший пример:.никсовые маны. Информационная плотность манов очень велика, воды там минимум, потому что они ориентированы на очень узкую ЦА, системных администраторов и внимательных энтузиастов.
Никому не придёт в голову писать для утилиты wc набор (five minute intro, ten minute intro, fifteen minute intro, faq, api reference, developer's manual). С другой стороны, если совокупная сложность продукта превышает определённый порог, иногда полезнее написать книгу, чем стописят манов, факов и экзамплов. Примеры из жизни: sendmail, bind. Книгами по подобным инструментам люди пользуются с куда как большим удовольствием, чем «родной» документацией. И почему, скажем, разработчикам байнда было сразу не написать увлекательную книжку, как поступили Крикет и Ли? Отдельный разговор — внутренняя документация для разработчиков. Для них иногда самая клёвая документация — это UML-диаграммы.
И больше не надо ничего. И вот как на это всё можно натянуть ГОСТ? На мой взгляд, никак. Польза ГОСТа, равно как и прочих стандартов, в, простите, стандартизации. То есть когда число продуктов начинает превышать какой-то обозримый минимум, возникает идея, что всё должно быть единообразно — для упрощения и ускорения процессинга этих самых продуктов. Если для академической среды это хорошо, не факт, что это будет хорошо для конечного потребителя. Другой момент — если люди не хотят напрягать мозг насчёт документации, они могут применить стандарты, и сэкономить на этом.
Если формат продукта такой, что это допустимо, ничего страшного нет. Если продукт клёвый (см. Выше), возможно, есть смысл задуматься, как применение стандартов отразится на конечных пользователях. (Хотя мне кажется, у авторов клёвых продуктов вообще изначально забота о пользователях выше.) Какие-то схемы, примеры и списки я приводить, пожалуй, не буду — кажется, особого смысла нет. Могу сказать, что для текущего продукта выбрал неформальный формат для руководства пользователя — почти полностью отказался от безличных оборотов, формальных конструкций языка, и вообще ориентируюсь на то, чтобы развлекать читателя.
Насколько это оправданно — покажет время. На самом деле в самих ГОСТ 19 серии (ЕСПД — единая система программной документации) написано — допускается устранять разделы и вводить новые. То есть, вы можете практически полностью изменить документ (обязательно должны быть титульный лист, содержание и аннотация) под ваши цели. В каких документах из числа предлагаемых ГОСТ представлять информацию?
Пожалуйста: 1. API, диаграммы классов, примеры написания кода — «Руководство программиста» (документ 13); 2. Конфигурирование, установка, удаление, использование системных утилит — «Руководство системного программиста» (документ 32).
Тут стоит сказать, что в момент создания ГОСТов этой серии «системными программистами» называли админов, в обязанности которых входило дописывание ОС под нужды программеров; 3. Инструкции для конечного пользователя — «Руководство оператора» (документ 34). Не можете подобрать подходящий документ — вводите свой со свободным номером. Да, есть явный конфликт между структурой ГОСТ и требованиями по «эргономике текста». Наверное, лучше все-таки, иметь стандартное РП и параллельно инструктивный материал по ролям участников процесса (некая разновидность технологической инструкции).
В свое время я экспериментировал со свободной формой. Не всем она по душе и не все разделяют энтузиазм создателей системы. По внутренней документации. Даже в нашем маленьком стартапе программисты не могут работать без постановок, которые готовят аналитики. У программистов нет фантазии, им это вообще не нужно. Постановка может содержать уже и Use Case, и эскизы интерфейсов и все, что угодно, чтобы программист понял задачу. Документация по ГОСТ сделана таким образом, что она может появляться вместе с системой, параллельно.
Не думаю, что популярную книжку можно написать до того, как появится предмет описания. А вот потом, глядя на готовую систему и (убогую) документацию к ней, можно уже выдать любой материал для любой аудитории, с картинками и цветными врезками. Есть типовое решение подобных вопросов, которое я знаю (оно не обязательно верное). Далее субъективное мнение. О пользе эскизного проекта я не слышал. Образно говоря, ЭП нужен для изъятия дополнительных дензнаков у заказчика.
Вам в итоге можно ограничиться двумя(тремя) документами. Пишете Пояснительную записку к техпроекту (П2), куда включаете необходимый вам контент в виде разделов по РД50 и руководство пользователя по ГОСТ. Если у вас приложение сложное в обслуживании, сделайте еще Руководство администратора (отдельная книжечка).
По сути это просто глава из РП, но так будет проще согласовывать. Заодно там будет минимально необходимый технический контент стадии РД (см. ГОСТ 34.602) Если заказчик вдруг запаникует и заговорит о ГОСТах, вы раздергаете контент П2 на отдельные «обеспечения» и все будет хорошо. По поводу «Чертежей формы документа (видеокадра)»: Очень полезный документ для визуализации/управления технологическими процессами, особенно когда согласован с технологами:) 2. По поводу «регламента работы службы эксплуатации»: он полностью вытекает из ПЗ, схемы функц.
Структуры и РЭ, иначе мы автоматизируем сферического коня в вакууме:) Другое дело, когда эту информацию предоставляет Заказчик в виде исходных данных, но это как договор составлен:) 3. ПЗ — это обычно самый ожидаемый и в итоге самый разочаровывающий документ, т.к. Исполнитель тупо запихивает в него ТЗ. По п.1 есть еще документ «Состав выходных данных (сообщений)», куда можно поместить все необходимые эскизы.
Там же обычно живут и отчетные формы. Часто приходится автоматизировать несуществующие бизнес-процессы. Чтобы опираться хоть на что-то, придумывается некий виртуальный бизнес-процесс, под который пишутся технические документы. Это ненормальная ситуация, но встречается сплошь и рядом. В нашей стране все еще свято верят в то, что с помощью хитрой программы можно решить проблемы бизнеса.
Стандарты призваны обеспечить совместимость между изделиями, разрабатываемыми в разных уголках страны. Представьте, что будет, если производители смесителей для ванн свой вид резьбы придумают и забью на стандарт?
Руководство Системного Программиста Гост Пример
Правильно, никто не сможет установить из смесители и продажи не пойдут. ГОСТ на программную документацию разрабатывался для упоорядочивания процесса разработки и обеспечения обмена информацией между разработчиками, трудящимися в различных учреждениях. Если вам придется синхронизировать процесс разработки с какой-либо сторонней организацией (заказать что-то на аутсорсинг, например), ГОСТ позволит вам ничего не изобретая составить перечень документов и запросить их подготовку в ТЗ.
А исполнитель не будет ломать голову над форматом изложения, например, правил написания конфига, а откроет ГОСТ, найдет структуру соответствующего документа и ее заполнит. Отличный материал выдали! Хорошо структурирован. Что же касается самого ГОСТ, то при разумном его использовании, можно создавать внятные и полезные документы. Если доки не просто формальная отписка и написаны толковыми спецами, то по ним вполне можно вникнуть как работает система, посмотреть на нее с разных аспектов. В чем готовите документы, если не секрет?
Трудяга Ворд? Слышал, что наиболее эффективно готовить в спецпакетах — Adobe FrameMaker и иже с ним. Сам никогда во FrameMaker, но судя по описанию принципа работы, подготовка комплекта документов в нем более гибка, чем в Ворде.