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

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

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

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

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

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

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

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

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

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

• применение современных методов и средств при реализации процессов ЖЦ изделия;
• взаимообмен конструкторской документацией без ее переоформления;
• безбумажное представление информации и использование электронной цифровой подписи;
• необходимую комплектность конструкторской документации;
• автоматизацию обработки КД и содержащейся в них информации;
• высокое качество изделий;
• наличие в конструкторской документации требований, обеспечивающих безопасность использования изделий для жизни и здоровья потребителей, окружающей среды, а также предотвращение причинения вреда имуществу;
• расширение унификации и стандартизации при проектировании изделий и разработке конструкторской документации;
• проведение сертификации изделий;
• сокращение сроков и снижение трудоемкости подготовки производства;
• правильную эксплуатацию изделий;
• оперативную подготовку документации для быстрой переналадки действующего производства;
• создание и ведение единой информационной базы;
• гармонизацию стандартов ЕСКД с международными стандартами (ИСО, МЭК) в области конструкторской документации;
• информационную поддержку ЖЦ изделия.

[из 4.2 ГОСТ 2.001–2013]».

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

Особо о «камне за пазухой», который ЕСКД приберегла для нерадивых разработчиков. Безобидный на первый взгляд пункт 7 указывает на ответственность разработчика в части реализации требований безопасности, пункт 11 заставляет задуматься о возможных негативных последствиях неправильной эксплуатации изделия.

Любая система стандартов не ограничивается исключительно требованиями безопасности — достаточно пролистать, к примеру, ГОСТ 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 г. — По вине автора в статью вкралась (и обитала в ней до указанной даты) неточность. Единый источник (исходник) предполагает всего лишь возможность публикации из чего-то исходного в электронные документы множества различных форматов и особого интереса не представляет. Интерес представляет возможность многократного повторного использования элементов данных (текста, графики, мультимедиа) — именно данный принцип лежит в основе автоматизации документирования. Автор приносит тысячу извинений всем тем, кому морочил голову более восьми лет.

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

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

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

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

1.3 Виды документов, разрабатываемых на стадиях «Эскизный проект», «Технический проект», «Рабочая документация» приведены в таблице 1.

[из 1.3 ГОСТ 34.201-89]

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

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

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

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

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

Обратите внимание на повторяемость элементов структуры — содержания разделов. Имеющиеся различия незначительны и сводятся к применению минимального набора клише:

• в ТЗ — «требования к…»;
• в пояснительной записке — «решения по…»;
• в общем описании системы — «описание…» и «сведения о…».

В итоге, повторяющиеся по существу разделы различных документов выглядят так:

Таким образом, жесткая взаимосвязь между структурными элементами отдельных документов, разрабатываемых в ходе создания АС, сомнений не вызывает. Для пущей убедительности имеет смысл проиллюстрировать вышеизложенное...

Типовое наполнение разделов технической документации

Техдокументация содержит и сохраняет от проекта к проекту множество типовых текстовых фрагментов. Если вернуться к подразделу «Специфические требования...», станет очевидным, что п. 7.1.69 ПУЭ был, есть и будет иметь место в проектах АИИС КУЭ независимо от того, для какого конкретного объекта электроэнергетики проект разрабатывается.

Перейдем к рассмотрению предпосылки за номером два — доступности специализированных средств разработки документации, построенных на основе концепции единого источника (исходника) — single source.

Современные специализированные программные средства, основанные на концепции единого источника

Современные специализированные программные средства, основанные на концепции единого источника, представлены как отечественными, так и зарубежными разработками. К наиболее популярным из них следует отнести AuthorIT от AuthorIT Software Corporation Ltd. и FrameMaker от Adobe. Указанные продукты близки по функциональности и доступны для приобретения. Автор окончательно определился в своих предпочтениях, поэтому дальнейшее повествование ведется применительно к AuthorIT. Но сначала — краткие сведения, необходимые для понимания концепции single source.

Примечание от 12.08.2020 г. — AuthorIT как десктоповый продукт по непонятным автору причинам исчез с рынка. Схожее с ним свободное ПО с открытым исходным кодом — проект Serna — закрылся. В настоящее время симпатию автора вызывает Docuvera, о которой чуть-–чуть ниже.

Чуть–чуть о Docuvera

Docuvera совсем недавно обнаружена на сайте AuthorIT Software Corporation Ltd. в ходе поиска свежей информации об AuthorIT. Поисковые машины выдают крайне мало информации о Docuvera, клип же становится безумно интересным с момента 1:26 мин просмотра. Обратной связи — как сделать buy, purchase или acquire — автор не нашел, но подписался на рассылку (мало ли чего любопытного всплывет).

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

Концепция единого исходника

Рисунок заимствован с сайта компании–производителя AuthorIT.

Концепция единого исходника предполагает возможность многократного повторного использования (reusing) данных — текстов, рисунков, гиперссылок с последующей «сборкой» и публикацией в файлы различных форматов. Перечисленные элементы хранятся в виде модулей данных в едином централизованном хранилище — базе данных (библиотеке). Модули (topics) текстовых фрагментов образуют книжки. Служебные модули содержат структуру разделов документов (table of contents), шаблоны разделов, стили, шаблоны разметки, требуемые при публикации документов. Каждому модулю присваивается уникальный код.

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

СУБД — программная оболочка

Для манипулирования с модулями данных база данных окружена программной оболочкой, состоящих из подсистем Authoring, Importer, Publisher, Project Manager и Administration.

Подсистема Authoring

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

Подсистема Importer

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

Подсистема Publisher

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

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

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

Подсистема Administration

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

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

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

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

Технический текст структурируется на разделы, подразделы, пункты, подпункты (см. п. 4.1 ГОСТ 2.105). В AuthorIT каждому из перечисленных структурных единиц соответствует шаблон — First Chapter Template (первый раздел документа), Chapter Template (любой другой раздел), Section Template (любой подраздел), Normal Template (пункт). Но ключевым шаблоном является No Heading Template. Если применить No Heading Template к текстовому разделу (модулю), то при публикации, к примеру, в документ Microsoft™ Word, текст раздела в документе отображается, а текст заголовка раздела отображаться не будет. Иными словами, при публикации в Microsoft™ Word такой раздел будет выглядеть отдельным абзацем под заголовком вышележащего уровня.

Как связать схожие разделы различных документов? Простой пример.

В подразделе «Назначение системы» технического задания набирается текст — «Система должна обеспечивать решение перечисленных ниже задач:». К указанному подразделу создается пункт с заголовком «ТЗ — перечень задач по назначению системы», к пункту применяется шаблон No Heading Template. При публикации документа заголовок указанного пункта отображаться не будет. В самом пункте записываются задачи, решаемые системой, в виде перечисления.

В разделе «Назначение системы» общего описания системы набирается текст «Система обеспечивает решение перечисленных ниже задач:». К указанному подразделу создается пустой (или содержащий любой текст) пункт на основе шаблона No Heading Template с заголовком «+(3) ТЗ — назначение системы». И, наконец, пункт технического задания «+(3) ТЗ — назначение системы» перетаскивается (drag and drop) во вновь созданный пункт пояснительной записки. Текст внедренного модуля будет выделен серым цветом.

Связь установлена. Теперь любые изменения внедренного модуля (подраздела ТЗ) будут автоматически сопровождаться изменением содержимого соответствующих подразделов пояснительной записки и других связанных с ТЗ документов. 100 % согласованность. Таким образом автором была сформирована библиотека типовых взаимоувязанных документов на АС.

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

Рисунок ниже иллюстрирует связи между структурами разделов документов. Использованы фрагменты реальных структур ТЗ на систему, пояснительной записки к проекту и общего описания системы. Разделы, содержащие в заголовках ТЗ, из ТЗ, П2, из П2, создаются на основе No Heading Template. Как отмечалось ранее, при публикации в Microsoft™ Word (и иные документы) заголовки разделов (на основе No Heading Template) не отображаются в текстах документов, а содержимое разделов - отображается.

Итоги

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

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

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

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

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

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

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

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

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

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

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

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

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

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