Автоматизация разработки технической документации. Часть I

Статья «Автоматизация разработки технической документации. Часть I» от 22.01.2005 г. открыла принципиально новые практические приемы разработки техдокументации. На основе первого (в нашей стране) успешного опыта автоматизации документирования показаны предпосылки к автоматизации жизненного цикла техдокументации. Да и вообще: любая автоматизация позволяет решить большинство проблем организационного характера техническим путем. Редакция от 16.12.2024.

Создан 22.01.2005 14:26:05

Бунтарям не жить на этой Земле...

М. Пушкина

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

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

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

• повышение управляемости жизненного цикла техдокументации;
• снижение трудоемкости и ресурсоемкости процессов жизненного цикла технической документации.

Задачи статьи:

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

Разработка технической документации — современная ситуация

Техническая документация: ее назначение (и отношение к ней)

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

• во избежание ответственности перед законом — на авиажаргоне такой подход называется «прикрытием задней полусферы»;
• для исключения возможных формальных претензий со стороны заказчика.

Указанный подход обеспечивает все предпосылки к разработке технической документации высочайшего качества. Ясно, что нести судебную ответственность и выплачивать денежную компенсацию за гибель животного американке, выстиравшей свою кошку в стиральной машине и высушившей любимицу в микроволновой печи, — дураков нет. Требуются лишь усилия разработчиков–профессионалов, помноженные на реализацию ими требований государственных стандартов (технических регламентов. Первая партия технических регламентов должна была увидеть свет во втором квартале 2005 года).

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

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

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

Примеры, по мнению автора, приводить бессмысленно. Многие неоднократно сталкивались и сталкиваются с совершенно бестолковой, размазанной, как манная каша по тарелке, писаниной. Писаниной, изданной в красочной суперобложке, на глянцевой бумаге. С глоссарием. С индексом. Сверстанной по «законам восприятия». И бесполезной в плане содержания. Usability в вульгарном, а не ГОСТовском смысле.

Тем не менее и компании–акулы, и мелкие любители национальной рыбалки в мутной водичке отечественного бизнеса едины в своем отношении к техдокументации, как минимум:

• вынужденным осознанием факта, что техническая документация должна быть;
• отсутствием интереса к процессу разработки (и т. д.) техдокументации.

С отношением и назначением покончено, теперь коротко о составе технической документации.

Техническая документация: состав

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

1. техническая документация на автоматизированные системы;
2. техническая документация на изделия;
3. техдокументация на программные изделия — программная документация.

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

С другой стороны, все то, что производится в современых условиях, проявляет все больше и больше признаков автоматизированных систем. Мобильный телефон, к примеру, трудно назвать изделием в классическом понимании. Вот ведро или лом — это точно изделия! Железно! И ничего больше. Тот же FineReader™ можно назвать программным изделием только на дистрибутивном носителе. После инсталляции FineReader начинает автоматически распознавать тексты — становится (в совокупности с программным и техническим обеспечением (средствами ПЭВМ) полноценной автоматизированной системой или системой обработки информации.

В ходе дальнейшего повествования ориентировка дается на проблемы серьезных компаний.

Техническая документация: жизненный цикл

Как бы то ни было, кто бы ни занимался разработкой техдокументации, каков бы ни был ее состав, обладает техническая документация, как и все в этом мире, собственным жизненным циклом. До слез понятно, даже без ссылок на всевозможные стандарты, что жизненный цикл техдокументации включает в себя, как минимум:

• процесс разработки технической документации;
• процесс публикации техдокументации как на бумажных носителях, так и в электронном виде;
• процессы учета и хранения технической документации;
• процессы модификации, отслеживания изменений техдокументации — сопровождения;
• процесс обмена технической документацией между подразделениями компании;
• процесс передачи техдокументации заказчику (или конечному пользователю).

Чем оборачивается разработчикам жизненный цикл технической документации? Шумихой, неразберихой, безответственностью — хаосом. Невиновных накажем, непричастных поощрим. Правда, встречаются и исключения.

В чем же причины воцарившегося хаоса? В типичной реализации жизненного цикла техокументации.

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

Зрелища, молитвы, хлеб,

Бой быков и винный погреб — чем не рай?!

Бунтовать желанья нет,

Сам учил нас — «Ближнего не обижай...»

М. Пушкина

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

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

Еще одна общая беда — электронная техническая документация не структурируется должным образом. Для разбиения электронной техдокументации на элементы данных — разделы, подразделы, пункты, подпункты — применяются:

• стили заголовков с многоуровневой нумерацией — особо продвинутыми пользователями (крайне редко);
• нумерованные списки — Microsoft™ Word достаточно «умен» и при попытках ручного ввода нумерации разделов иногда пытается автоматически разбить сплошной текст на разделы и подразделы в виде нумерованных списков;
• выделение строки абзацного текста жирным шрифтом и ручной ввод номера раздела — лишь бы на бумаге все выглядело «изячно», если угодно — «элегантно».

Так ведь и претензии предъявить нельзя! У того же проджект–менеджера основная задача — не владение Microsoft™ Word'ом на уровне продвинутого пользователя, а получение подписи заказчика на акте приемки–сдачи работ. Мотивация, пардон, отсутствует.

О хранении — электронная техдокументация хранится в структуре каталогов пользовательских компьютеров и серверов. Естественно, абы как. Российский менталитет–с. Структура пользовательских каталогов хаотична. Где что лежит — в лучшем случае вспомнит лишь хозяин. Названия файлов электронной технической документации также не отличаются единообразием и удобочитаемостью. Резервное копирование файлов электронной техдокументации, как правило, не производится, что приводит к утрате документов.

Об учете — попытки поставить классический учет бумажных документов терпит фиаско. Уследить за всеми участниками процесса разработки нереально. Время заказ–нарядов на машинописные работы давным–давно прошло. Быстро не «только кошки плодятся», но и документация. И также «промискуитетно».

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

Об обмене технической документацией внутри компании. Затребовали — отправил документ электронной почтой или показал, в каком каталоге сетевого диска документ хранится. Позднее внес в документ изменения. Не затребовали — не передал. Сбросить на расшаренный сетевой диск или на svn поленился, решил отложить на завтра — и благополучно обо всем забыл.

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

Как избежать бардака? Лаской (по проф. Преображенскому) не удается. Грозными санкциями — тоже. Единственная надежда на автоматизацию, благо все предпосылки имеют место быть.

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

Каковы же предпосылки к автоматизации процессов жизненного цикла технической документации? Вот они:

• доступность специализированных средств разработки текстовых документов, построенных на основе концепции единого источника (исходника — single source) с возможностью многократного повторного использования текстов, графики, мультимедиа, гиперссылок и т.д.;
• замечательные особенности советской нормативно–технической документации.

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

Специализированных средств разработки технической (да и любой документации) навалом. Производятся таковые как отечественными компаниями, так и буржуйскими. Средства известные, на слуху, подробно останавливаться и приводить сравнительный анализ особого смысла нет. Предпочтения автора сводятся к применению при разработке (сопровождении и т.д.) техдокументации программы AuthorIT от AuthorIT Software Corporation Ltd.

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

Электронная техдокументация хранится в едином централизованном хранилище — в базе данных. AuthorIT позволяет применять в качестве базы данных как MS SQL, так и отдельные файлы библиотек. А вот MySQL, увы, пока не позволяет. Библиотеки структурно подразделяются на книги, книги на разделы и подразделы, пункты и подпункты (топики) — аж до девяти уровней вложенности. Собственно топики и являются атомарными модулями данных или элементами данных, если по ГОСТ Р 52292. Топики (модули данных), инкапсулируя в себе содержимое разделов и подразделов книг, содержат также и служебную информацию — шаблоны разметки. Каждому модулю данных присваивается уникальный код (ключ) согласно системы кодирования или название (силами пользователя).

База данных окружена оболочкой, в общем случае, включающей в себя:

• подсистему Authoring;
• подсистему Importer;
• подсистему Publisher;
• подсистему Project Manager;
• подсистему Administration.

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

Подсистема Importer обеспечивает возможность импорта документов из файлов различных форматов (включая *.doc и *.htm) с сохранением структуры и содержания разделов документа во внутреннем формате AuthorITT. Есть нюансы: попытка импорта неправильно структурированного вордовского документа не пройдет. Особенно, если такой файл содержит кучу OLE–объектов (ActiveX) и сложные колонтитулы.

Подсистема Publisher обеспечивает возможность сборки документов из модулей (элементов) данных внутреннего формата AuthorIT, публикации технической документации в различных форматах help–файлов, а также в формате Microsoft™ Word. Вордовые файлы получаются замечательными — никаких проблем с кириллицей и т.п. Важно только настроить шаблон — это просто.

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

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

Таким образом, AuthorIT обеспечивает возможность одновременной работы многих пользователей с библиотекой. Права и полномочия пользователей разделены на основе аутентификации и авторизации. Иными словами, изменения, внесенные в библиотеку конкретным пользователем, автоматически фиксируются с указанием имени пользователя, даты, времени и характера внесенных им изменений.

Имеется возможность сравнения различных версий, скажем, версий одного и того же раздела, с указанием — кто, что и когда добавил, изменил или удалил. Версии разделов легко «поменять местами».

Теперь о составе и особенностях советской нормативно–технической документации (НТД), применяемой при создании автоматизированных систем, изделий и программных изделий.

НТД, применяемая при создании систем, изделий и программных изделий

Не далее, как 18 января 2005 года, на стол автора свалилась Программа разработки технических регламентов, утвержденная распоряжением Правительства РФ от 06 ноября 2004 г. за № 1421–р. Что будут представлять собой технические регламенты — младенцу понятно. В лучшем случае старые советские ГОСТы единой тематики будут собраны в одну кучу и опубликованы единым документом с названием «регламент». В худшем — регламенты будут «цельнотянутыми» с буржуйских, «цельнотянутых» во время оно с советских ГОСТов. О прелестях двойного перевода говорить, уверен, даже не стоит.

Примечание от 10.02.2010 г. — Так и вышло. Вернее, ничего толком и не вышло — 500 регламентов так и не были разработаны.

Состав НТД

В настоящее время основополагающим документом при создании автоматизированных систем, изделий и программных изделий является техническое задание (на создание АС — ГОСТ 34.602–89.) Техзадание останется основополагающим документом и в обозримом будущем. Неважно, как будет называться этот документ — все равно это будет техническое задание.

Примечание от 07.06.2014 г. — Так оно и есть.

В ряде подразделов техзадания приводится перечень нормативно–технической документации (НТД), на основании которой создается система. Любая НТД, приведенная в указанном разделе согласованного и утвержденного технического задания, обретает силу закона как для заказчика, так и для исполнителя.

В целом для создания любого вида АС перечень НТД должен включать в себя:

• ГОСТ 34.601–90, регламентирующий стадии и этапы создания АС — описание процессов в их хронологическом порядке;
• ГОСТ 34.201–89, регламетирующий виды, комплектность и обозначения (наименования) документов, разрабатываемых на стадиях и этапах проведения работ по созданию АС;
• РД 50–34.689–90, регламентирующий требования к содержанию документов на АС;
• ряд ГОСТ 2 (ЕСКД), регламентирующих требования к содержанию и оформлению документов на изделия, входящие в состав АС;
• ГОСТ 2.601–95, регламентирующий требования к эксплуатационной документации на изделия, входящие в состав АС;
• ряд ГОСТов 19–й системы (ЕСПД), регламентирующих требования к содержанию и оформлению документов на программные изделия, входящие в состав АС;
• ряд ГОСТов, по которым можно оценить качество технической документации — ГОСТ 28195–89, ГОСТ 28806–90;
• плюс ГОСТы (технические регламенты) предметной области.

Это был состав, теперь об особенностях.

Особенности НТД для разработки АС

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

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

Нынешним разработчикам остается только поблагодарить специалистов, принимавших участие в создании советских стандартов на автоматизированные системы, изделия и программные изделия. Как в фильме «Максим Перепелица», устами «диду Мусию» (роль сыграл совсем молодой Г. Вицин): «Спасибо тебе, Кондрат, за такого сына!».

Следует отметить, что разработка стандартов в советские времена считалась «высшим пилотажем». К разработке привлекались специалисты наивысшей квалификации, коих сейчас, к сожалению, осталось немного. Коллективы разработчиков, как правило, становились лауреатами Государственных премий.

Повторяемость структуры и содержания ТД на АС

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

Как гласит латинская поговорка — умному достаточно. Повторяющиеся элементы структуры имеют незначительные различия:

• в ТЗ применяются штампы (клише) «требования к…»;
• в ПЗ применяются штампы «решения по…»;
• в ООП применяются штампы «описание…» и «сведения о…».

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

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

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

Пример. К эксплуатации системы допускается персонал:

• аттестованный на группу по электробезопасности не ниже III;
• прошедший курсы обучения ... на предприятии–изготовителе;
• и так далее...

Как ни крути, а указанный текстовый фрагмент не претерпевает изменений при копировании его из техзадания в руководство пользователя.

Более сложный пример. В техническом задании — система должна обеспечивать выполнение перечисленных ниже функций:

• функции такой–то;
• функции сякой–то;
• и так далее...

В руководстве пользователя — система обеспечивает выполнение (или обеспечивает возможность выполнения, если функция не автоматическая, а автоматизированная) перечисленных ниже функций:

• функции такой–то;
• функции сякой–то;
• и так далее...

Разница выделена жирным шрифтом.

Вот и все о предпосылках. Теперь о практической реализации такого подхода к разработке технической документации с применением программы AuthorIT.

Практическая реализация жизненного цикла технической документации

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

Дла начала следует скачать триальную версию AuthorIT с сайта производителя (потребуется ни к чему не обязывающая регистрация), установить оную на пользовательском компьютере, запустить и создать новую библиотеку на основе sample.adl, обозвать ее как–нибудь и закрыть (вместе с программой). По умолчанию имя пользователя — supervisor, пароля никакого, полномочия пользователя — административные.

У автора имеется разработанная им же библиотека взаимоувязанных документов, содержащая пока только документацию на автоматизированные системы по ГОСТ 34.602–89 и РД 50–34.698–90. Считаем, что в распоряжении читателя подобная библиотека документов также имеется.

Далее решаются проблемы множественности участников процесса разработки технической документации.

Разграничение прав и полномочий пользователей

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

1. запуском модуля AuthorIT Administrator;
2. открытием файла библиотеки (вход с именем пользователя supervisor);
3. созданием пользователей (групп пользователей);
4. назначением им паролей;
5. перекрытием кислорода.

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

Всем группам пользователей следует запретить возможность публикации документов и изменения шаблонов документов — вся техническая документация компании должна публиковаться одним ответственным лицом — supervisor'ом. Эд(т)акая узкая горловина–воронка. Как ранее, когда без подписи нормоконтролера ни один документ не смел покинуть пределы родной фабрики. Заодно решается и проблема стилевого оформления документов.

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

Поскольку библиотека взаимоувязанных документов уже создана, а supervisor должен быть умным, документация структурирована и детализирована до атомарного уровня по умолчанию.

Допустим, проектант, привыкший к ворду, налепил в топике пояснительной записки, содержащейся в библиотеке взаимоувязанных документов, сплошной неструктурированный текст. Что делать с товарищем? Возможные варианты:

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

Дело вкуса. Люди все разные, кто–то осваивается быстро, кого–то обучить в принципе ничему невозможно. В любом случае, правку в единой библиотеке документов сделать проще, нежели в куче разрозненных и неподдающихся контролю документов. И всегда остается возможность ткнуть товарища в следы его жизнедеятельности в библиотеке документов, поскольку все изменения фиксируются и хранятся с указанием даты, времени, автора и характера внесенных изменений.

Проблема учета и хранения техдокументации также оказывается решенной. При работе в многопользовательском режиме с базой MS SQL пользователь, не обладая специальными навыками, стащить такую базу на свой компьютер не сможет. Копировать файлы библиотек также бессмысленно, поскольку публикация документов проходит через узкую горловину supervisor'а и без его подписи ни один бумажный документ не имеет юридической силы.

Для разработки очередного типового проекта создается очередная копия файла библиотеки документов. Совокупность таких файлов автоматически формирует реестр проектов.

Проблема сопровождения техдокументации также оказывается решенной. Любые изменения, внесенные в соответствующие документы группой пользователей, немедленно отражаются во всех взаимосвязанных документах библиотеки. Документация становится согласованной, различные документы, входящие в состав библиотеки, не противоречат друг другу.

Проблема обмена техдокументации между подразделениями компании оказывается исключенной. Есть база MS SQL или библиотека взаимоувязанных документов — какой смысл создавать копии и передавать их друг другу, если они изначально являются общедоступным ресурсом?

Вот приблизительная схема взаимодействия персонала подразделений компании с общим ресурсом (при использовании триальной версии AuthorIT):

ОУП — отдел управления проектами, команда проджект–менеджеров.

ПСД — проектно–сметная документация.

На всех стадиях и этапах проведения работ по созданию системы изменения в технической документации фиксируются автоматически с указанием даты, времени и авторства, взаимоувязанные документы обновляются автоматически.

Техдокументация передается заказчику «выпускающим редактором» в лице supervisor'а, с неотъемлемым набором утверждающих подписей и печатей. Или на оптическом носителе в формате pdf (что не имеет особого смысла. FineReader «колет» pdf–файлы, как белочка орешки. И при этом имеет наглость сохранять распознанное в ворде с сохранением формата оригинала).

Разработка библиотеки взаимоувязанных документов

Теперь, когда показано, что большинство проблем при реализации жизненного цикла технической документации можно решить средствами автоматизации, можно перейти к десерту — показать, в чем же фишка? А фишка проста, как все гениальное (соответствующий смайлик). Возможно, читатель обратил внимание на то, что настоящая статья содержит всего десяток–полтора заголовков разделов. На самом деле это не так. Разделов (и заголовков) в исходном документе AuthorIT'овской библиотеки примерно втрое больше, чем заголовков.

Все дело в AuthorIt'овском шаблоне с названием no heading. При применении указанного шаблона к топику (разделу документа) внутри библиотеки, текст топика при публикации, к примеру, в вордовый документ, отображается, а заголовок раздела — нет. На основе такого подхода и построена разработка библиотеки типовых документов.

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

Осточертевший всем пример. В топике раздела документа техническое задание «Требования к численности ... персонала» записывается фраза — «Численность персонала, обслуживающего систему, должна обеспечивать:». К указанному разделу создается подраздел «ТЗ — перечень требований к численности персонала» на основе шаблона no heading. При публикации документа заголовок указанного подраздела отображаться не будет.

В подразделе записывается перечисление:

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

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

В топике раздела документа пояснительная записка «Решение по численности ... персонала» записывается фраза «Согласно требованиям технического задания численность персонала, обслуживающего систему, обеспечивает:». К указанному разделу также создается подраздел на основе шаблона no heading «из ТЗ — перечень требований к численности персонала». И, наконец, прямо в текст подраздела перетаскивается топик «ТЗ — перечень требований к численности персонала» из технического задания. Текст вставленного топика автоматически выделяется серым цветом.

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

Квалификация supervisor'а

Скоро сказка сказывается, да не скоро дело делается. Казалось бы — а что такого? Перетаскивай топики из техзадания в схожие топики пояснительной записки, руководств и прочих документов. Опутывай библиотеку типовых документов сетью взаимных ссылок — и все, вопрос решен. Сажаем девочку и все будет работать само собой.

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

В ходе разработки библиотеки сформировались требования к квалификации сотрудника, способного претендовать на роль supervisor'а — эд(т)акого кота–методиста, сумеющего не только создать библиотеку, но и поддерживать ее в актуальном состоянии. Необходимый минимум:

• многолетний опыт разработки техдокументации согласно требованиям ГОСТов;
• многолетний опыт взаимодействия с заказчиком на всех стадиях и этапах проведения работ по созданию автоматизированных систем, изделий, программных изделий;
• многолетняя практика взаимодействия с «немотивированными» сотрудниками смежных подразделений компании;
• умение создать из страницы бестолкового текста короткий абзац с тремя–четырьмя четкими формулировками;
• грамотное применение штампов (клише) в техническом русском языке;
• и, наконец, знание компьютерной техники на уровне, приближающемся к уровню системного администратора.

Знания предметной области желательны, но необязательны.

Заключение

Что ж, цели достигнуты, задачи решены... К сожалению, глаз автора уже «замылен»: вещи, изложенные в статье, для автора очевидны. Возможно, остались вопросы без ответов. Задать вопросы можно в форуме — Форум разработчиков технической документации.

Все. Если г–да маститые технические писатели (техписы) не поленились и прочли статью до конца — попинать или отлупить автора без нанесения тяжких телесных повреждений также можно в форуме. Бейте разумное, доброе, вечное...