Впервые опубликована в журнале «Мир Автоматизации» № 3 за 2006 год с названием «Ваш выбор?»
|
|
|
|
Разработка изделий, программных изделий, создание автоматизированных систем сопровождаются разработкой технической документации (ТД) - так было, есть и будет. Но для множества компаний разного «калибра» разработка ТД по сей день остается занятием в немалой степени рутинным, трудоемким и ресурсоемким, а результаты - сомнительными. Причина - проблемы организационно-технического и методического характера.
Проблемы известны и во многом обусловлены отношением к ТД (и к ее разработке), как к чему-то вторичному. Тем не менее, вынужденное осознание факта, что ТД должна быть, служит серьезным стимулом к снижению рутинности, трудоемкости и ресурсоемкости разработки путем автоматизации. Особенно при значительных объемах и разноплановости технической документации.
Попытки автоматизации внедрением современных систем электронного документооборота решают проблемы лишь частично - для большинства таких систем «атомарным» объектом является документ, представленный отдельным файлом. Разработчик же манипулирует структурными элементами - разделами, подразделами, пунктами, подпунктами и абзацами текста.
Предлагаемый подход, позволяющий учесть специфику процесса разработки ТД, избавиться от рутины, существенно снизить трудоемкость и ресурсоемкость, повысить качество ТД, реализован автором на практике и показал убедительные результаты. Повествование ведется в контексте применения ГОСТ при разработке ТД в ходе создания автоматизированных систем (АС).
|
|
|
|
Для опытных разработчиков основным мотивом применения ГОСТ представляется разумность добровольного (см. ФЗ РФ № 184 от 27.12.2002 «О техническом регулировании») следования общеизвестным, проверенным годами и признанным государством правилам игры. Цитата из п. 3.2 ГОСТ 2.001-93 (ЕСКД):
«Основное назначение стандартов ЕСКД состоит в установлении единых оптимальных правил выполнения, оформления и обращения конструкторской документации, которые обеспечивают:
Не вызывает сомнений факт, что ЕСКД (и иные системы стандартов) направлена на достижение взаимной удовлетворенности хозяйствующих субъектов. Найдется ли Заказчик, готовый отказаться от высокого качества изделий? Заинтересованы ли Заказчик и Исполнитель в сокращении сроков производства, в оптимальной комплектности документации? Ответы очевидны.
Особо о «камне за пазухой», который ЕСКД приберегла для нерадивых разработчиков. Безобидный на первый взгляд пункт 6 указывает на ответственность разработчика в части реализации требований безопасности, пункт 10 заставляет задуматься о возможных последствиях неправильной эксплуатации изделия.
Любая система стандартов не ограничивается исключительно требованиями безопасности - достаточно пролистать, к примеру, ГОСТ 34.602-89, содержащий громадный набор требований к создаваемой АС. Кое-кто попытается возразить - мол, ГОСТ 34.602-89 безнадежно устарел, его невозможно применить на практике. Отнюдь нет.
Скептики, с немалым удивлением, обнаружат, что к современным АС предъявляются те же принципиальные требования - структурные, функциональные и технические, изложенные в стандарте почти тридцатилетней давности. А какие же качественно новые принципиальные требования предъявляют, к примеру, к ПО по прошествии тридцати лет? Пожалуй, требования к графическому пользовательскому интерфейсу. Но разве ГОСТ 19.201-78 исключает формулировку указанных требований в техническом задании (ТЗ)?
Знание требований стандартов, способность грамотно, не допуская множественных трактовок, сформулировать требования в ТД, дает разработчику возможность избежать проблем как при проектировании, так и после ввода изделия или АС в промэксплуатацию.
|
|
|
|
При проектировании АС волей-неволей приходится сталкиваться с надзорными органами (Энергонадзор, Госсвязьнадзор и т.д). Одной из задач надзорных органов является экспертиза ТД, предоставленной разработчиком, на соответствие требованиям «отраслевых» стандартов. Энергонадзор, к примеру, ревностно следит за соответствием ТД требованиям ПУЭ.
Исключить взаимодействие с надзорными органами невозможно. Смонтированная на объекте Заказчика полностью работоспособная автоматизированная информационно-измерительная система коммерческого учета электроэнергии (АИИС КУЭ) так и останется «незаконнорожденной», если ТД не будет согласована в Энергонадзоре. Энергонадзор попросту не даст «добро» на ввод системы в промэксплуатацию.
|
|
|
|
После ввода изделия или АС в промэксплуатацию возможны как формальные претензии к Исполнителю со стороны Заказчика (из-за неоднозначно трактуемых формулировок в ТД), так и более серьезные претензии.
Исключить формальные претензии Заказчика возможно единственным способом - разработкой стопроцентно согласованной (непротиворечивой) ТД с учетом требований ГОСТ. Проектные решения должны полностью удовлетворять требованиям ТЗ, эксплуатационные документы - строго соответствовать проектным решениям. Согласованная и не допускающая множественного толкования ТД послужит отличной доказательной базой в арбитраже.
Ситуация из области охраны труда - банковский клерк гибнет от поражения электрическим током при прикосновении к безобидной настольной лампе. Запускается формальнейшая процедура расследования, в ходе которой выясняется, что злосчастный клерк не был аттестован на II группу по электробезопасности и не имел права не то что пользоваться настольной лампой, но и приближаться к ней на расстояние пушечного выстрела.
Кто виноват? Банковский юрист предъявит суду руководство по эксплуатации лампы-убийцы, в котором не найдется ни слова о соблюдении персоналом правил электробезопасности. Сложно сказать, кто ответит за невинно-убиенного. Возможно, ответственность ляжет на компанию-производителя, а руководство банка отделается легким испугом. Вот, к чему может привести незнание и неприменение требований нормативов при разработке ТД.
|
|
|
|
В ряд подразделов ТЗ по ГОСТ 34.602-89 включается перечень нормативно-технической документации (НТД), на основании которой создается АС. Любая НТД, упомянутая в подразделах согласованного и утвержденного ТЗ, обретает силу Закона как для Заказчика, так и для Исполнителя. Ведь ТЗ разрабатывается на основании Договора и является неотъемлемой его частью, а Договор между хозяйствующими субъектами - в компетенции действующего законодательства.
|
|
|
|
Общие требования к документам, разрабатываемым в ходе создания АС, изложены в ГОСТ 34. Виды и комплектность документов регламентируются ГОСТ 34.201-89. Основополагающим является ТЗ на АС по ГОСТ 34.602-89, требования к структуре и содержанию ТД на АС изложены в РД 50-34.689-90. Перечисленное - всего лишь необходимый минимум, не учитывающий специфических требований к создаваемой АС.
|
|
|
|
Специфические требования, предъявляемые к каждому конкретному виду АС, сформулированы в соответствующей «отраслевой» НТД. Так, к примеру, п. 7.1.69 ПУЭ (Правил эксплуатации электроустановок) гласит - «В помещениях зданий металлические корпуса однофазных переносных электроприборов и настольных средств оргтехники класса I по ГОСТ 12.2.007.0-75 «ССБТ. Изделия электротехнические. Общие требования безопасности» должны присоединяться к защитным проводникам трехпроводной групповой линии».
Стоит ли напоминать, что наличие такой формулировки в подразделах «Требования безопасности» (или «Подготовка объекта автоматизации к вводу системы в действие») ТЗ, проектной, рабочей и эксплуатационной документации обязательно? А вот конкретные требования по защите информации от несанкционированного доступа следует заимствовать из Руководящего документа Гостехкомиссии «Автоматизированные системы. Защита от несанкционированного доступа к информации. Классификация автоматизированных систем и требования по защите информации» в зависимости от заявленного Заказчиком класса защищенности создаваемой АС.
|
|
|
|
Как же «объять необъятное», учесть требования огромного количества НТД, придать разрабатываемой ТД «стройный строгий вид», избавиться от рутины и не вступить в конфликт с Законом? Необходимые и достаточные предпосылки налицо. К ним относятся:
|
|
|
|
НТД, применяемая при разработке ТД, обладает рядом очевидных и полезных особенностей:
|
|
|
|
Рассмотрим виды документов, разрабатываемых на стадиях и этапах создания АС (п. 1.3 ГОСТ 34.201-89).
Вид документа |
Код документа |
Назначение документа |
Ведомость |
В |
Перечисление в систематизированном виде объектов, предметов и т. д. |
Схема |
С |
Графическое изображение форм документов, частей, элементов системы и связей между ними в виде условных обозначений |
Инструкция |
И |
Изложение состава действий и правил их выполнения персоналом |
Обоснование |
Б |
Изложение сведений, подтверждающих целесообразность принимаемых решений |
Описание |
П |
Пояснение назначения системы, ее частей, принципов их действия и условий применения |
Конструкторский документ |
|
По ГОСТ 2.102 |
Программный документ |
|
По ГОСТ 19.101 |
Напомним, что основополагающим документом при создании АС является ТЗ. ТЗ содержит обязательный к исполнению перечень требований к системе, которые должны быть реализованы в ходе создания АС. Реализация требований подтверждается проведением испытаний.
«Обоснования» указывают, как разработчик подтверждает целесообразность принимаемого им решения. Но решения не могут существовать в отрыве от требований - так подавляющая часть текста требований «перекочевывает» из технического задания во все документы-обоснования. А как пояснить в описании назначение системы и ее частей без использования в описании текста требований по назначению из ТЗ?
Становится очевидным, что все виды документов, разрабатываемых на стадиях и этапах создания АС, являются взаимоувязанными. Более того, взаимоувязанными на уровне структурных единиц документов - разделов, подразделов, пунктов и подпунктов, отдельных абзацев. Рассмотрим последнее утверждение детально.
|
|
|
|
В таблице сопоставлены требования к содержанию разделов ТЗ, пояснительной записки к проекту и общего описания системы.
документ |
содержание разделов |
техническое задание |
1) перечень подсистем, их назначение и основные характеристики, требования к числу уровней иерархии и степени централизации системы; 2) требования к способам и средствам связи для информационного обмена между компонентами системы; 3) требования к характеристикам взаимосвязей создаваемой системы со смежными системами, требования к ее совместимости, в том числе указания о способах обмена информацией (автоматически, пересылкой документов, по телефону и т. п.); 4) требования к режимам функционирования системы; 5) требования по диагностированию системы; 6) перспективы развития, модернизации системы. |
Пояснительная записка |
1) решения по структуре системы, подсистем, средствам и способам связи для информационного обмена между компонентами системы, подсистем: 2) решения по взаимосвязям АС со смежными системами, обеспечению ее совместимости; 3) решения по режимам функционирования, диагностированию работы системы; |
Общее описание системы |
2.11.3. В разделе «Описание системы» указывают: 1) структуру системы и назначение ее частей; 2) сведения об АС в целом и ее частях, необходимые для обеспечения эксплуатации системы; 3) описание функционирования системы и ее частей. 2.11.4. В разделе «Описание взаимосвязей АС с другими системами» указывают: 1) перечень систем, с которыми связана данная АС; 2) описание связей между системами; 3) описание регламента связей; 4) описание взаимосвязей АС с подразделениями объекта автоматизации. |
Обратите внимание на повторяемость элементов структуры - содержания разделов. Имеющиеся различия незначительны и сводятся к применению минимального набора клише:
В итоге, повторяющиеся по существу разделы различных документов выглядят так:
Требования к |
режимам функционирования системы |
Решения по |
режимам функционирования системы |
Сведения о |
режимах функционирования системы |
Таким образом, жесткая взаимосвязь между структурными элементами отдельных документов, разрабатываемых в ходе создания АС, сомнений не вызывает. Для пущей убедительности имеет смысл проиллюстрировать вышеизложенное:
|
|
|
|
ТД содержит и сохраняет от проекта к проекту множество типовых текстовых фрагментов. Если вернуться к подразделу «Специфические требования...», станет очевидным, что п. 7.1.69 ПУЭ был, есть и будет иметь место в проектах АИИС КУЭ независимо от того, для какого конкретного объекта электроэнергетики проект разрабатывается.
Перейдем к рассмотрению предпосылки за номером два - доступности специализированных средств разработки документации, построенных на основе концепции единого источника (исходника) - single source.
|
|
|
|
Современные специализированные программные средства, основанные на концепции единого источника, представлены как отечественными, так и зарубежными разработками. К наиболее популярным из них следует отнести AuthorIT от AuthorIT Software Corporation Ltd. и FrameMaker от Adobe. Указанные продукты близки по функциональности и доступны для приобретения.
Автор окончательно определился в своих предпочтениях, поэтому дальнейшее повествование ведется применительно к AuthorIT. Но сначала - краткие сведения, необходимые для понимания концепции single source.
|
|
|
|
Рисунок заимствован с сайта компании-производителя AuthorIT.
Концепция единого исходника предполагает возможность многократного повторного использования данных - текстов, рисунков, гиперссылок с последующей «сборкой» и публикацией в файлы различных форматов. Перечисленные элементы хранятся в виде модулей данных в едином централизованном хранилище - базе данных (библиотеке). Модули текстовых фрагментов образуют книжки. Служебные модули содержат структуру разделов документов (table of contents), шаблоны разделов, стили, шаблоны разметки, требуемые при публикации документов. Каждому модулю присваивается уникальный код.
С помощью механизма, подобного OLE, возможна организация связей между модулями внутри библиотеки. Так, к примеру, в модуль текста можно включить любой другой модуль текста, рисунок, объект мультимедиа. В случае, если во внедренный объект будут внесены изменения, изменения претерпят все связанные модули.
|
|
|
|
Для манипулирования с модулями данных база данных окружена программной оболочкой, состоящих из подсистем Authoring, Importer, Publisher, Project Manager и Administration.
|
|
|
|
Подсистема Authoring - текстовый процессор с пользовательским интерфейсом, очень схожим с MS Word - средство создания, редактирования, отображения и сохранения документов - книжек библиотеки. Подсистема обеспечивает возможность единовременной многопользовательской работы с библиотекой на уровне модуля, поддерживает разграничение прав и полномочий пользователей на основе аутентификации и авторизации.
|
|
|
|
Подсистема Importer обеспечивает возможность импорта в библиотеку документов из файлов различных форматов (doc, html, rtf, mif). Импорт документов существенно облегчает работу - проще импортировать в библиотеку текст ГОСТ, отсканированный с бумажного источника, «распознанный» и сохраненный в MS Word, чем набирать его вручную.
|
|
|
|
Подсистема Publisher обеспечивает сборку документов из модулей и публикацию документов в файлы формата doc, pdf, html, hlp, html-help. Возможна пакетная публикация всего содержимого библиотеки во все форматы, выборочная публикация.
|
|
|
|
Подсистема Project Manager обеспечивает стандартные возможности управления проектами.
|
|
|
|
Подсистема Administration обеспечивает возможность управления библиотекой, правами пользователей, контроля версий (кто, когда и какие изменения внес, возможность отмены изменений), создания различных отчетов.
|
|
|
|
Базируясь на изложенных выше соображениях и технических возможностях AuthorIT, можно приступить к практической реализации подхода к автоматизации разработки ТД с применением средств разработки на основе single source.
|
|
|
|
Технический текст структурируется на разделы, подразделы, пункты, подпункты (ГОСТ 2.105-95). В AuthorIT каждому из перечисленных структурных единиц соответствует шаблон - First Chapter Template (первый раздел документа), Chapter Template (любой другой раздел), Section Template (любой подраздел), Normal Template (пункт). Но ключевым шаблоном является No Heading Template. Если применить No Heading Template к текстовому разделу (модулю), то при публикации, к примеру, в документ MS Word, текст раздела в документе отображается, а текст заголовка раздела отображаться не будет. Иными словами, при публикации в MS Word такой раздел будет выглядеть отдельным абзацем под заголовком вышележащего уровня.
Как связать схожие разделы различных документов? Простой пример.
В подразделе «Назначение системы» технического задания набирается текст - «Система должна обеспечивать решение перечисленных ниже задач:». К указанному подразделу создается пункт с заголовком «ТЗ - перечень задач по назначению системы», к пункту применяется шаблон No Heading Template. При публикации документа заголовок указанного пункта отображаться не будет. В самом пункте записываются задачи, решаемые системой, в виде перечисления.
В подразделе «Назначение системы» пояснительной записки набирается текст «Система обеспечивает решение перечисленных ниже задач:». К указанному подразделу создается пустой (или содержащий любой текст) пункт на основе шаблона No Heading Template с заголовком «из ТЗ - перечень задач по назначению системы». И, наконец, пункт технического задания «ТЗ - перечень задач по назначению системы» перетаскивается (drag and drop) во вновь созданный пункт пояснительной записки. Текст внедренного модуля будет выделен серым цветом.
Связь установлена. Теперь любые изменения внедренного модуля (подраздела ТЗ) будут автоматически сопровождаться изменением содержимого соответствующих подразделов пояснительной записки и других связанных с ТЗ документов. 100% согласованность. Таким образом автором была сформирована библиотека типовых взаимосвязанных документов на АС.
|
|
|
|
Рисунок ниже иллюстрирует связи между структурами разделов документов. Использованы фрагменты реальных структур ТЗ на систему, пояснительной записки к проекту и общего описания системы. Разделы, содержащие в заголовках ТЗ, из ТЗ, П2, из П2, создаются на основе No Heading Template. Как отмечалось ранее, при публикации в Word (и иные документы) заголовки разделов (на основе No Heading Template) не отображаются в текстах документов, а содержимое разделов - отображается.
|
|
|
|
|
|
|
|
Жесткая связь между схожими (или идентичными) разделами (подразделами, пунктами, подпунктами) отдельных документов обеспечила возможность внесения изменений во все документы комплекта одним «легким движением руки». К примеру, требуется внести изменения в подраздел «Назначение системы», имеющий место практически во всех проектных и эксплуатационных документах. Вариантов два:
В первом случае разработчика ждет приятная перспектива двадцатикратного:
Казалось бы, при выборе второго варианта трудоемкость снизится раз в двадцать. Так ли это на самом деле? А что будет, если изменения в подразделы двадцати документов будут вносить не один, а несколько человек, в разное время и в разные копии документов?
|
|
|
|
Как количественно оценить степень готовности к публикации? Ясно, что степень готовности весьма высока. До 90 %, если проект совсем уж типовой. Прихватив на встречу с Заказчиком ноутбук, в ходе беседы можно не только подготовить проект технического задания на основе «типового библиотечного», но и автоматически сформировать проектную и эксплуатационную документацию. К завершению беседы Заказчика можно приятно удивить оперативностью и организованностью, предъявив ему практически готовый комплект документации на систему.
|
|
|
|
Зачем держать штат нормоконтролеров? Все документы публикуются с применением единого шаблона, однажды разработанного по ЕСКД, поэтому в части оформления документы выглядят, как близнецы-братья.
|
|
|
|
Как применить библиотеку типовых документов в иной предметной области, не связанной с автоматизированными информационно-измерительными системами коммерческого учета электроэнергии?
Опыт такого применения имеется. К автору обратился Заказчик, представитель известной группы компаний, область деятельности которой - информационные технологии. Задача - в кратчайшие сроки разработать техническое задание и технический проект (всего 11 текстовых документов) в рамках программы «Электронная Россия».
Скорее из любопытства, чем из-за финансовых соображений, автор статьи взялся за разработку. Заказчик оказался весьма компетентным в предметной области, аккуратно поставлял «сырой», но конкретный материал. Оставалось только определиться со структурой системы, сформулировать цели и задачи, расписать функции каждой из подсистем, а затем разбросать наработанный материал по уже связанным разделам (подразделам, пунктам, подпунктам) библиотеки типовых документов. В результате такого взаимодействия проект общероссийского масштаба был разработан в течение девяти (!) дней - две пары выходных плюс вечернее время с 19 до 22 часов. И утвержден «Заказчиком Заказчика».
Информация об авторских правах - все товарные знаки и торговые марки, упомянутые в материалах сайта, принадлежат законным владельцам. Все материалы, опубликованные на сайте без указания авторства в явном виде, принадлежат исключительно владельцам домена authorit.ru. Все материалы, опубликованные на сайте с явным указанием авторства, принадлежат исключительно авторам, предоставившим указанные материалы. Убедительная просьба ко всем, кто в коммерческих или иных целях намерен использовать материалы сайта - поимейте совесть и ссылайтесь на первоисточник в своих Интернет-ресурсах.