• новости, помощь наших специалистов
• применение ГОСТ 19, применение ГОСТ34
• образцы документов, публикации
• критика, о жизни, консультации в форуме
• книга об AuthorIT

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

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

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

Каковы первые практические итоги создания библиотеки типовых документов?

Практические итоги создания библиотеки типовых документов

Практические итоги таковы:

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

Снижение трудоемкости разработки технической документации

Снижение трудоемкости разработки технической документации достигнуто:

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

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

Глупо изобретать велосипед, имея опыт эксплуатации сотен систем, созданных с применением типовых проектных решений (ТПР). Разумно единожды сформулировать указанные решения и проводить их от проекта к проекту, от документа к документу.

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

Нет-нет, это не пост «технического писателя всех времен и народов». Техпис «думает» с точностью до «наоборот». Это пост специалиста, настоящего разработчика, посещающего Форум разработчиков электроники. Коллега неправ лишь в одном - насчет 95% затрат времени на разработку технической документации. Но с момента опубликования поста до момента опубликования настоящей статьи прошло более полугода. Балласт, звезд с неба не хватающий, пора сокращать и приглашать одного-двух специалистов-системотехников.

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

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

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

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

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

Во втором случае изменения во всех прочих документах производятся автоматически.

Повышение согласованности технической документации

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

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

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

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

Вот и все. В данном случае решения и сведения идентичны. Налицо 100% согласованность технического задания, пояснительной записки (П2) и общего описания системы (ПД) (в рамках единого проекта, разумеется).

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

Как связь разделов документов выглядит в AuthorIT

Небольшое отступление. Поступила, с позволения сказать, «критика снизу», от «технического писателя всех времен и народов». «Техпис всех времен и народов», как всегда, смотрел в книгу, а увидел фигу в визивиге.

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

Самое забавное состоит в том, что никакой «многоуровневый импорт материала по ссылкам», никакого «исключительного внимания» и не требуется. Достаточно один единственный раз прочесть РД 50-34.698-90, чтобы один единственный раз реализовать связку разделов документов, после чего скромно почивать на лаврах. Для этого надо просто уметь читать. Но «чукча не читатель, чукча - писатель».

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

А теперь немного о том, насколько «эффективно» сам «технический писатель всех времен и народов» применяет программные средства на основе single source. Напомним, что фреймейкер - софтина недешевая и обошлась конторе, в которой имеет удовольствие просиживать штаны указанный «мастер технического слова», примерно в $ 5000.

Все применение single source сведено к тупой вставке раздела «Работа с электронным документом», см. рисунок выше. Для такой вставки и ворда более чем достаточно.

Фреймейкер - продукт далеко не самый удачный: проблемы с кириллицей, бестолковый пользовательский интерфейс, необходимость приобретать продукты третьих фирм, чтобы хоть как-то заставить фреймейкер сносно работать. Говорят, правда, что может работать с документами в сотни тысяч страниц. Тем не менее, использовать софтинку так, как использует ее «техпис всех времен и народов», все равно, что забивать гвозди электронным микроскопом.

Повышение степени готовности к выпуску комплекта технической документации

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

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

Сейчас проще. Прихватив на встречу ноутбук, можно не только подготовить проект технического задания на основе «типового библиотечного», но заодно автоматически сформировать проектно-сметную и эксплуатационную документацию. Если при постановке задачи в целом антагонистические противоречия между Заказчиком и Исполнителем не выявлены, техническое задание следует тут же распечатать и подсунуть Заказчику на подпись. Заказчик будет приятно удивлен оперативностью и организованностью Исполнителя.

Как количественно оценить степень готовности? Ясно только, что степень готовности весьма высока. До 90 %, если проект совсем уж типовой.

Исключение нормоконтроля текстовых документов

Нормоконтроль изничтожен, как класс (в части оформления). Все документы публикуются с применением единого шаблона, однажды разработанного по ГОСТ 2.104-68, ГОСТ 2.105-95 (и т.п.) и прошедшего нормоконтроль по полной программе. Все документы - близнецы-братья.

Выводы по разделу

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

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

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

Цели и задачи

Библиотека типовых документов использовалась до последнего времени по большей части индивидуально. А как на практике реализовать коллективную работу с библиотекой в рамках компании?

Цели - прежние и столь же благородные: упростить, улучшить, снизить, повысить, уменьшить, увеличить - и так далее.

Задачи:

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

Решение второй задачи «кажется» автору статьи неколько более важным.

О судьбе «удаленных» сотрудников

К «удаленным» сотрудникам можно причислить:

• откомандированных сотрудников;
• фрилансеров.

О судьбе командированного

Командировки ломают судьбы.

Командированного никто не любит и не жалеет - ни Заказчик, ни собственное руководство. Командированный никому не нужен. Командированный, застряв недели на три у особо вредного Заказчика, где-нибудь у черта на рогах - в Усть-@@@@юйске, вкушает столовские обеды, обитает в гостиничном «нумере» с типовым набором прелестей, простирывая в ржавом умывальнике воротнички и манжеты. Ему тоскливо, холодно и бесконечно одиноко. А дома - жены, дети (и так далее).

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

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

Многое, конечно, зависит от сроков. Те, кому приходилось выезжать на полгода и более, в один голос утверждают, что кризис (когда хочется послать все и всех в известном направлении, но нельзя) наступает ближе к сороковому дню. Совпадение? Зато потом - все по-барабану. Проходили.

В военное время бывает иначе. В Афгане небольшое подразделение попало так, что в течение полутора недель кушать приходилось только промерзший консервированный зеленый горошек. Курить нельзя, огонь разводить нельзя: чуть дымок - тут же обстрел. Минометный. Бриться пытались насухо, отточенным штык-ножом. К месту или нет, но информация - со слов участников событий.

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

О судьбе фрилансера

Быть фрилансером, казалось бы, хорошо. Сиди себе на даче, в тенечке, кроши (crush) батоны (buttons) на клаве (on keyboard), да сбрасывай готовенькое в контору через спутниковый канал (или GPRS - кому как повезет). Ни тебе автомобильных пробок, ни давки в метро. И денежка на кредитку капает.

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

Все сотрудники должны находиться на рабочих местах. Сидит сотрудник за столом - значит, работает. И совершенно неважно, чем занят сотрудник - мочит ли он в сети фашистов в компании таких же трудоголиков, или, как истинный анархист-индивидуалист, в гордом одиночестве гоняет шарики или раскладывает пасьянсы. Главное - человек на рабочем месте. Следовательно, работает.

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

Исходные данные

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

Технические средства

Автором при макетировании использовалась машинка где-то 1999 года выпуска, на базе семисотмегагерцового селерона со 128 Мб оперативной памяти и винчестером около 8 Гб. Сетевая карта пятидолларовая, без встроенного процессора. Такого хлама в любой компании навалом, многие не знают, как от него избавиться. Автор коллекционирует динозавровиков и использует оных для экспериментов: в качестве линуксовых маршрутизаторов и web-серверов. Под Linux такая техника работает весьма шустро и надежно, работает годами без необходимости переустановки операционной системы. И волки (авторы) сыты, и овцы (логистики) целы.

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

На перспективу админ порекомендовал сервер на базе Xeon с памятью от 512 Мб, зеркалированными винчестерами. Сетевая карта - соответствующая, со встроенным процессором. Конфигурация в расчете на 10-15 одновременно законнектившихся к БД пользователей.

Для подключения к локальной сети компании придется выпросить у админа пару патчкордов и поискать гнезда RJ-45. Если свободных гнезд нет, придется приобрести или выклянчить у админа пятипортовый switch. Стоит такой switch копейки - от 15 до 30 условных.

Программные средства

Потребуется Win 2000 Server и MS SQL Server 2000 Standard Edition. Такого добра (разумеется, лицензионного) у админа навалом. Админ также выделит под MS SQL Server статический IP-адрес.

Вот, собственно, и все.

Пошаговая реализация

Установка MS SQL Server

После подключения сетевой карты компьютера к локальной сети можно начинать установку Win 2000 Server. На Win 2000 Pro MS SQL Server устанавливаться не будет.

Процесс установки и настройки Win 2000 Server - без особенностей. Следует назначить сетевой карте статический IP-адрес, выделенный админом, а при настройке сервера указать, что сервер самый обычный, а не какой-нибудь контроллер домена и т.д.

Процесс установки MS SQL Server - также без особенностей. В самом начале установки следует выбрать кнопочку Install Database Server, далее тупо жать Next. По завершении установки при настройке разрешить коннект к базам данных MS SQL пользователям с учетными записями Win (пользователям домена).

Включение сервера MS SQL в домен

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

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

Настройка пользовательского компьютера

На каждом пользовательском компьютере в разделе Администрирование панели управления придется открыть Источники данных (ODBC) и настроить драйвер MS SQL Server на вкладке User DSN. Заодно можно проверить коннект пользовательского компьютера с базой данных MS SQL.

Создание баз данных библиотек

Создание базы данных под библиотеку выполняется средствами MS SQL Server. Просто добавляется пустая база данных с требуемым именем, например, sample или test. Лучше с тем же именем, что и файл библиотеки.

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

Экспорт файлов библиотек в БД библиотек

С пользовательского компьютера с установленной Evaluation версией AuthorIT запускается AuthorIT Administrator. Administrator'ом следует загрузить файл требуемой библиотеки с локального компьютера, после чего экспортировать указанный файл в ранее созданную пустую БД библиотеки на MS SQL Server. Для экспорта придется ввести в окошко статический IP-адрес, присвоенный MS SQL Server, указать имя ранее созданной БД (sample или test), а также установить флажок Use Trusted Connection.

Вот и все. Далее запускается AuthorIT и открывается БД библиотеки с сервера MS SQL. Огорчает лишь одно - AuthorIT Evaluation не пустит к открытой БД другого пользователя. Работать с сетевой БД библиотеки типовых документов придется поочередно всем заинтересованным гражданам.

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

Особенности реализации для удаленной работы

При удаленной работе, когда БД библиотеки документов хранится на офисных серверах, системному администратору придется открыть, как минимум, 445 порт (ms-sql - см. RFC 1700) брандмауэра на входящие соединения. Админы ох как не любят открывать порты, тем более, что IP-адрес входящего соединения в 99% случаев будет динамическим. Брешь в сетевой защите, пробитая осознанно и собственными руками. С другой стороны, можно отправить проджекта в командировку с локальным файлом библиотеки, но затем сложно будет засинхронизироваться.

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

Заключение

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

Информация об авторских правах - все товарные знаки и торговые марки, упомянутые в материалах сайта, принадлежат законным владельцам. Все материалы, опубликованные на сайте без указания авторства в явном виде, принадлежат исключительно владельцам домена authorit.ru. Все материалы, опубликованные на сайте с явным указанием авторства, принадлежат исключительно авторам, предоставившим указанные материалы. Убедительная просьба ко всем, кто в коммерческих или иных целях намерен использовать материалы сайта - поимейте совесть и ссылайтесь на первоисточник в своих Интернет-ресурсах.

Версия для печати