Автоматизация разработки ТД с применением инструментария на основе single source

Разработка изделий, программных изделий, создание автоматизированных систем сопровождаются разработкой технической документации (ТД) - так было, есть и будет. Но для множества компаний разного «калибра» разработка ТД остается занятием рутинным, трудоемким и ресурсоемким, а результаты - сомнительными. Причины понятны, выход - в автоматизации разработки технической документации. Редакция от 06.10.2014.

Создан 27.03.2006 17:59:56

Впервые опубликована в журнале «Мир Автоматизации» № 3 за 2006 год.

-Мир Автоматизации № 3 2006

Проблема известна и во многом обусловлена отношением к техдокументации (и к ее разработке), как к чему-то вторичному, если не ненужному вообще. Тем не менее, вынужденное осознание факта, что техническая документация должна быть, служит серьезным стимулом к снижению рутинности, трудоемкости и ресурсоемкости ее разработки путем автоматизации, особенно при значительных объемах и разноплановости техдокументации.

Попытки автоматизации внедрением современных систем электронного документооборота или контроля версий решают проблемы лишь частично - для большинства таких систем «атомарным» объектом является документ, представленный отдельным файлом. Разработчик же, согласно п. 4.1 ГОСТ 2.105, манипулирует структурными элементами документа - разделами, подразделами, пунктами, подпунктами и абзацами.

Предлагаемый в статье подход, позволяющий учесть специфику процесса разработки ТД, избавиться от рутины, существенно снизить трудоемкость и ресурсоемкость, повысить качество техдокументации, реализован автором на практике и показал отличные результаты. Повествование ведется в контексте применения ГОСТов при разработке технической документации в ходе создания автоматизированных систем (АС).

Примечание от 26.12.2011 г. - С момента первой реализации технологии автоматизированного документирования осенью 2004 г. автором, а в дальнейшем и компанией «Техническая документация», выполнены десятки различных комплектов документов, с отдельными из них можно ознакомиться в разделе Проекты портала.

Смотрите:
Мотивы к применению ГОСТ при разработке технической документации
Общие требования к документам, разрабатываемым в ходе создания системы
Специфические требования к создаваемой системе
Предпосылки к практической реализации авторского подхода
Практическая реализация
Итоги
Вместо заключения

Мотивы к применению ГОСТ при разработке технической документации

Для опытных разработчиков основным мотивом применения ГОСТов представляется разумность добровольного (см. ФЗ РФ № 184 от 27.12.2002 «О техническом регулировании») следования общеизвестным, проверенным годами и признанным государством правилам игры. Цитата из п. 3.2 ГОСТ 2.001-93 (ЕСКД):

«Основное назначение стандартов ЕСКД состоит в установлении единых оптимальных правил выполнения, оформления и обращения конструкторской документации, которые обеспечивают:

  1. применение современных методов и средств при проектировании изделий;
  2. возможность взаимообмена конструкторской документацией без ее переоформления;
  3. оптимальную комплектность конструкторской документации;
  4. механизацию и автоматизацию обработки конструкторских документов и содержащейся в них информации;
  5. высокое качество изделий;
  6. наличие в конструкторской документации требований, обеспечивающих безопасность использования изделий для жизни и здоровья потребителей, окружающей среды, а также предотвращение причинения вреда имуществу;
  7. возможность расширения унификации и стандартизации при проектировании изделий;
  8. возможность проведения сертификации изделий;
  9. сокращение сроков и снижение трудоемкости подготовки производства;
  10. правильную эксплуатацию изделий;
  11. оперативную подготовку документации для быстрой переналадки действующего производства;
  12. упрощение форм конструкторских документов и графических изображений;
  13. возможность создания единой информационной базы автоматизированных систем (САПР, АСУП и др.);
  14. гармонизацию с соответствующими международными стандартами».

Не вызывает сомнений факт, что ЕСКД (и иные системы стандартов) направлена на достижение взаимной удовлетворенности хозяйствующих субъектов. Найдется ли заказчик, готовый отказаться от высокого качества изделий? Заинтересованы ли заказчик и исполнитель в сокращении сроков производства, в оптимальной комплектности документации? Ответы очевидны.

Особо о «камне за пазухой», который ЕСКД приберегла для нерадивых разработчиков. Безобидный на первый взгляд пункт 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. особенности НТД, применяемой при разработке технической документации;
  2. доступность специализированных средств разработки документации, построенных на основе концепции единого источника (исходника) - single source.

Примечание от 15.06.2014 г. - По вине автора в статью вкралась (и обитала в ней до указанной даты) неточность. Единый источник (исходник) предполагает всего лишь возможность публикации из чего-то исходного в электронные документы множества различных форматов и особого интереса не представляет. Интерес представляет возможность многократного повторного использования элементов данных (текста, графики, мультимедиа) - именно данный принцип лежит в основе автоматизации документирования. Автор приносит тысячу извинений всем тем, кому морочил голову более восьми лет - Круглые глаза

Смотрите:
Особенности НТД, применяемой при разработке технической документации
Виды документов, разрабатываемых на стадиях и этапах создания автоматизированных систем
Взаимоувязанность, повторяемость структуры и содержания технической документации
Типовое наполнение разделов технической документации
Современные специализированные программные средства, основанные на концепции единого источника
Концепция единого исходника
СУБД - программная оболочка
Подсистема Authoring
Подсистема Importer
Подсистема Publisher
Подсистема Project Manager
Подсистема Administration

Особенности НТД, применяемой при разработке технической документации

НТД, применяемая при разработке техдокументации, обладает рядом очевидных и полезных особенностей:

  • взаимосвязью, повторяемостью структуры и содержания большинства документов;
  • типовым наполнением разделов большинства документов.

Виды документов, разрабатываемых на стадиях и этапах создания автоматизированных систем

Рассмотрим виды документов, разрабатываемых на стадиях и этапах создания АС.

Вид документа

Код документа

Назначение документа

Ведомость

В

Перечисление в систематизированном виде объектов, предметов и т. д.

Схема

С

Графическое изображение форм документов, частей, элементов системы и связей между ними в виде условных обозначений

Инструкция

И

Изложение состава действий и правил их выполнения персоналом

Обоснование

Б

Изложение сведений, подтверждающих целесообразность принимаемых решений

Описание

П

Пояснение назначения системы, ее частей, принципов их действия и условий применения

Конструкторский документ

По ГОСТ 2.102

Программный документ

По ГОСТ 19.101

[из табл. 1 п. 1.3 ГОСТ 34.201-89]

Напомним, что основополагающим документом при создании АС является техзадание. Техническое задание содержит обязательный к исполнению перечень требований к системе, которые должны быть реализованы в ходе создания АС. Реализация требований подтверждается проведением испытаний.

«Обоснования» указывают, как разработчик подтверждает целесообразность принимаемого им решения. Но решения не могут существовать в отрыве от требований - так подавляющая часть текста требований «перекочевывает» из технического задания во все документы-обоснования. А как пояснить в описании назначение системы и ее частей без использования в описании текста требований по назначению из техзадания?

Становится очевидным, что все виды документов, разрабатываемых на стадиях и этапах создания АС, являются взаимоувязанными. Более того, взаимоувязанными на уровне структурных единиц документов - разделов, подразделов, пунктов и подпунктов, отдельных абзацев. Рассмотрим последнее утверждение детально.

Взаимоувязанность, повторяемость структуры и содержания технической документации

В таблице сопоставлены требования к содержанию разделов техзадания (ТЗ), пояснительной записки к проекту и общего описания системы.

Документ

Содержание разделов

Техническое задание

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

Подсистема Authoring - текстовый процессор с пользовательским интерфейсом, очень схожим с MS Word - средство создания, редактирования, отображения и сохранения документов - книжек библиотеки. Подсистема обеспечивает возможность единовременной многопользовательской работы с библиотекой на уровне модуля, поддерживает разграничение прав и полномочий пользователей на основе аутентификации и авторизации.

Подсистема Importer

Подсистема Importer обеспечивает возможность импорта в библиотеку документов из файлов различных форматов (doc, html, rtf, mif). Импорт документов существенно облегчает работу - проще импортировать в библиотеку текст ГОСТа, отсканированный с бумажного источника, «распознанный» и сохраненный в MS Word, чем набирать его вручную.

Подсистема Publisher

Подсистема Publisher обеспечивает сборку документов из модулей и публикацию документов в файлы формата doc, pdf, html, hlp, html-help. Возможна пакетная публикация всего содержимого библиотеки во все форматы, выборочная публикация.

- Подсистема Publisher

Подсистема Project Manager

Подсистема Project Manager обеспечивает стандартные возможности управления проектами.

Подсистема Administration

Подсистема Administration обеспечивает возможность управления библиотекой, правами пользователей, контроля версий (кто, когда и какие изменения внес, возможность отмены изменений), создания различных отчетов.

Практическая реализация

Базируясь на изложенных выше соображениях и технических возможностях AuthorIT, можно приступить к практической реализации подхода к автоматизации разработки технической документации с применением средств разработки на основе single source.

Смотрите:
Методика связывания разделов документов
Иллюстрация связей структур документов

Методика связывания разделов документов

Технический текст структурируется на разделы, подразделы, пункты, подпункты (см. п. 4.1 ГОСТ 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) не отображаются в текстах документов, а содержимое разделов - отображается.

- Связь структур ТЗ, П2, ПД

Итоги

Смотрите:
Снижение трудоемкости
Повышение степени готовности к публикации
Исключение издержек на нормоконтроль

Снижение трудоемкости

Жесткая связь между схожими (или идентичными) разделами (подразделами, пунктами, подпунктами) отдельных документов обеспечила возможность внесения изменений во все документы комплекта одним «легким движением руки». К примеру, требуется внести изменения в подраздел «Назначение системы», имеющий место практически во всех проектных и эксплуатационных документах. Вариантов два:

  1. внести изменения в каждый отдельный документ (а документов, положим, двадцать);
  2. внести изменения только в техническое задание.

В первом случае разработчика ждет приятная перспектива двадцатикратного:

  • открытия отдельного документа;
  • поиска указанного подраздела;
  • копирования-вставки;
  • закрытия отдельного документа.

Казалось бы, при выборе второго варианта трудоемкость снизится раз в двадцать. Так ли это на самом деле? А что будет, если изменения в подразделы двадцати документов будут вносить не один, а несколько человек, в разное время и в разные копии документов?

Повышение степени готовности к публикации

Как количественно оценить степень готовности к публикации? Ясно, что степень готовности весьма высока. До 90 %, если проект совсем уж типовой. Прихватив на встречу с заказчиком ноутбук, в ходе беседы можно не только подготовить проект техзадания на основе «типового библиотечного», но и автоматически сформировать проектную и эксплуатационную документацию. К завершению беседы заказчика можно приятно удивить оперативностью и организованностью, предъявив ему практически готовый комплект документации на систему.

Исключение издержек на нормоконтроль

Зачем держать штат нормоконтролеров? Все документы публикуются с применением единого шаблона, однажды разработанного по ЕСКД, поэтому в части оформления документы выглядят, как близнецы-братья.

Вместо заключения

Как применить библиотеку взаимоувязанных документов в иной предметной области, не связанной с автоматизированными информационно-измерительными системами коммерческого учета электроэнергии?

Опыт такого применения имеется. К автору обратился заказчик, представитель известной группы компаний, область деятельности которой - информационные технологии. Задача - в кратчайшие сроки разработать техническое задание и технический проект (всего 11 текстовых документов) в рамках программы «Электронная Россия».

Скорее из любопытства, чем из-за финансовых соображений, автор статьи взялся за разработку. Заказчик оказался весьма компетентным в предметной области, аккуратно поставлял «сырой», но конкретный материал. Оставалось только определиться со структурой системы, сформулировать цели и задачи, расписать функции каждой из подсистем, а затем разбросать наработанный материал по уже связанным разделам (подразделам, пунктам, подпунктам) библиотеки взаимоувязанных документов. В результате такого взаимодействия проект общероссийского масштаба был разработан в течение девяти (!) дней - две пары выходных плюс вечернее время с 19 до 22 часов. И утвержден «заказчиком заказчика».