Практические результаты применения библиотек взаимоувязанных документов при автоматизированной разработке технической документации, пошаговая реализация коллективной работы с библиотекой взаимоувязанных документов в рамках организации. Редакция от 12.11.2024.
Создан 18.04.2005 9:59:26
В статье «Автоматизация разработки технической документации. Часть I» были рассмотрены предпосылки, исходные данные, подходы и некоторые практические приемы автоматизации процессов жизненного цикла технической документации. Практическая реализация подходов привела к созданию библиотеки взаимоувязанных документов, сопровождающих проектирование и ввод в эксплуатацию автоматизированных систем.
В настоящее время библиотека содержит свыше двадцати (взаимоувязанных разделами, подразделами, пунктами и подпунктами) типовых документов, включая техзадание (ГОСТ 34.602–89), проектно–сметные и эксплуатационные документы (РД 50–34.698–90). В течение последнего времени проводилась (и продолжается) опытная эксплуатация библиотеки.
Каковы первые практические результаты создания библиотеки взаимоувязанных документов?
Примечание — Здесь и далее по тексту настоящим временем следует считать дату первой публикации — 18.04.2005 г.
Далее: |
Практические результаты создания и применения библиотек взаимоувязанных документов
Практические результаты создания и применения библиотек взаимоувязанных документов таковы:
- существенно снижена трудоемкость разработки техдокументации;
- до предельного уровня возросла согласованность технической документации;
- многократно повысилась степень готовности к выпуску комплекта техдокументации;
- исключен нормоконтроль текстовых документов в части их оформления.
Снижение трудоемкости разработки технической документации
Снижение трудоемкости разработки техдокументации достигнуто:
- применением типовых проектных решений;
- организацией жесткой связи между схожими (или идентичными) логическими элементами структуры документов комплекта.
Множество проектных решений 100–процентно «обкатаны» — неоднократно подвергались испытаниям, принимались комиссиями самых разных уровней, продемонстрировали свою надежность и, самое главное, оправдали себя в ходе промышленной эксплуатации. Практика — критерий истины. Указанные проектные решения можно смело причислить к типовым.
Глупо изобретать велосипед, имея опыт эксплуатации сотен систем, созданных с применением типовых проектных решений (ТПР). Разумно единожды сформулировать указанные решения и проводить их от проекта к проекту, от документа к документу.
Один «маститый технический писатель всех времен и народов» высказался по поводу ТПР: типа, грош цена документации, в которой содержание разделов статично. Он пошутил...
Это не пост «технического писателя всех времен и народов». Техпис «думает» с точностью до «наоборот». Это пост специалиста, посещающего форум разработчиков электроники. Коллега неправ лишь в одном — насчет 95 % затрат времени на разработку техдокументации. Но с момента опубликования поста до момента опубликования настоящей статьи прошло более полугода. Балласт, звезд с неба не хватающий, пора сокращать и приглашать одного–двух специалистов–системотехников.
Жесткая связь между схожими (или идентичными) разделами (подразделами, пунктами, подпунктами) отдельных документов обеспечила возможность внесения изменений во все документы комплекта одним «легким движением руки». К примеру, требуется внести изменения в подраздел «Перечень задач, решаемых системой», который в том или ином виде имеет место практически во всех проектно–сметных и эксплуатационных документах. «Произрастает» указанный подраздел из технического задания. Вариантов два:
- внести изменения в каждый отдельный документ (а документов, положим, двадцать);
- внести изменения только в техническое задание.
В первом случае разработчика ждет приятная перспектива двадцатикратного:
- открытия отдельного документа;
- поиска указанного подраздела;
- выделения подраздела;
- нажатия кнопки Вставить;
- закрытия отдельного документа.
Казалось бы, при выборе второго варианта трудоемкость снизится раз в двадцать. Так ли это? А что будет, если изменения в подразделы двадцати документов будут вносить не один, а несколько человек, в разное время и в разные копии документов?
Во втором случае изменения во всех прочих документах производятся автоматически.
Повышение согласованности технической документации
Согласованность — главное требование к технической документации, выражающееся в непротиворечивости сведений, излагаемых в отдельных документах, входящих в состав комплекта техдокументации.
Если в техническом задании прописано некое требование, в проектных документах должно иметь место решение, обеспечивающее выполнение указанного требования. Если требование имеется, а решение отсутствует или не соответствует требованию — налицо противоречие (несогласованность). Если имеется решение, но отсутствует соответствующее требование — это инициатива. Исполнитель оказывает себе медвежью услугу, поскольку инициатива всегда была наказуема исполнением.
Из требований и решений складываются сведения, необходимые и достаточные для понимания принципа действия и правильной эксплуатации системы. Указанные сведения должны иметь место в эксплуатационных документах.
В «описательных» эксплуатационных документах, не требующих действий пользователя системы, большая часть сведений становится результатом «порОчной» связи требований и решений. Например:
Вот и все. В данном случае решения и сведения идентичны. Налицо 100–процентная согласованность технического задания, пояснительной записки (П2) и общего описания системы (ПД) (в рамках единого проекта, разумеется).
В «инструктирующих» эксплуатационных документах, при изучении которых пользователь вынужден предпринимать какие–либо действия (жать кнопки), все чуть сложнее. Но 100–процентная согласованность всех перечисленных документов остается незыблемой.
Как связь разделов документов выглядит в AuthorIT
Небольшое отступление. Поступила, с позволения сказать, «критика снизу», от «технического писателя всех времен и народов». «Техпис всех времен и народов», как всегда, смотрел в книгу, а увидел...
«Критик», как ни странно, прав. Т.н. «техническому писателю», ковыряющему совочком в своей песочнице, такая работа не под силу. Вероятность ошибки — 100–процентная. И даже не из–за отсутствия квалификации, а оттого, что задачи у техписов не те. Техписы заняты форматированием табличек, всякими врезками, сносками, кеглями и прочей типографской шелухой. Задача техписа — сверстать текст, созданный разработчиком, сделать все «красиво». В общероссийском классификаторе такая профессия называется «укладчик текста». А ежели техпису доверяют «написание» документации — тушите свет. Не зря говорят, что руководства пользователя читаются с трудом, а пишутся через ... Сии руководства — плоды жизнедеятельности техписов.
Самое забавное состоит в том, что никакой «многоуровневый импорт материала по ссылкам», никакого «исключительного внимания» и не требуется. Достаточно один единственный раз прочесть РД 50–34.698–90, чтобы один единственный раз реализовать связку разделов документов, после чего скромно почивать на лаврах. Для этого надо просто уметь читать. Но «чукча не читатель, чукча — писатель».
Картинка ниже наглядно показывает связи между подразделами документов. Использованы фрагменты реальных структур технического задания на систему, пояснительной записки к проекту и общего описания системы. Разделы, содержащие в заголовках ТЗ, из ТЗ, П2, из П2, создаются на основе шаблона no heading. Как отмечалось ранее, при публикации в Word (и иные документы) заголовки разделов (на основе шаблона no heading) не отображаются в текстах документов, а содержимое разделов — отображается.
А теперь немного о том, насколько «эффективно» сам «технический писатель всех времен и народов» применяет программные средства на основе single source. Напомним, что фреймейкер — софтина недешевая и обошлась конторе, в которой имеет удовольствие просиживать штаны указанный «мастер технического слова», примерно в $ 5000.
Все применение single source сведено к тупой вставке раздела «Работа с электронным документом», см. рисунок выше. Для такой вставки и ворда более чем достаточно.
Фреймейкер — продукт далеко не самый удачный: проблемы с кириллицей, бестолковый пользовательский интерфейс, необходимость приобретать продукты третьих фирм, чтобы хоть как–то заставить фреймейкер сносно работать. Говорят, правда, что может работать с документами в сотни тысяч страниц. Тем не менее, использовать софтинку так, как использует ее «техпис всех времен и народов», все равно, что забивать гвозди электронным микроскопом.
Повышение степени готовности к выпуску комплекта технической документации
Повышение степени готовности к выпуску комплекта техдокументации оценить также нелегко, как и снижение трудоемкости.
В былые времена, когда автоматизировать процессы жизненного цикла технической документации не представлялось возможным из–за отсутствия некоторых предпосылок (см. Автоматизация разработки технической документации. Часть I), автору неоднократно приходилось наблюдать картину — при первой же беседе с потенциальным заказчиком любимый шеф аккуратно пишет что–то в рабочую тетрадку. Любопытство не поощрялось, но к моменту завершения встречи становилось ясно, что в тетрадке шефа — черновик техзадания, «технический облик» будущей системы.
Сейчас проще. Прихватив на встречу ноутбук или планшет, можно не только подготовить проект технического задания на основе «библиотечного», но заодно автоматически сформировать проектную и эксплуатационную документацию. Если при постановке задачи в целом антагонистические противоречия между заказчиком и исполнителем не выявлены, техзадание следует тут же распечатать и подсунуть заказчику на подпись. Заказчик будет приятно удивлен оперативностью и организованностью исполнителя.
Как количественно оценить степень готовности? Ясно только, что степень готовности весьма высока. До 90 %, если проект совсем уж типовой.
Исключение нормоконтроля текстовых документов
Нормоконтроль уничтожен как класс (в части оформления). Все документы публикуются с применением единого шаблона, однажды разработанного по ГОСТ 2.104–68, ГОСТ 2.105–95 (и т.п.) и прошедшего нормоконтроль по полной программе. В части оформления все документы — близнецы–братья.
Выводы по разделу
Как применить библиотеку взаимоувязанных документов в иной предметной области, не связанной с автоматизированными информационно–измерительными системами коммерческого учета электроэнергии?
Опыт такого применения имеется. К автору обратился заказчик, представитель известной группы компаний, область деятельности которой — информационные технологии. Задача — в кратчайшие сроки разработать техническое задание и технический проект (всего 11 текстовых документов) в рамках программы «Электронная Россия».
Скорее из любопытства, чем из–за финансовых соображений, автор статьи взялся за разработку. Заказчик оказался весьма компетентным в предметной области, аккуратно поставлял «сырой», но конкретный материал. Оставалось только определиться со структурой системы, сформулировать цели и задачи, расписать функции каждой из подсистем, а затем разбросать наработанный материал по ранее уже связанным разделам (подразделам, пунктам, подпунктам) библиотеки взаимоувязанных документов. В результате такого взаимодействия проект общероссийского масштаба был разработан в течение девяти (!) дней — две пары выходных плюс вечернее время с 19 до 22 часов. И утвержден «заказчиком заказчика».
Цели и задачи
Библиотека взаимоувязанных документов использовалась до последнего времени по большей части индивидуально. А как на практике реализовать коллективную работу с библиотекой в рамках компании?
Цели — прежние и столь же благородные: упростить, улучшить, снизить, сократить, повысить, уменьшить, увеличить — и так далее.
Задачи:
- показать способ технической реализации коллективной работы с библиотекой взаимоувязанных документов в рамках офиса организации;
- та же, но для «удаленных» сотрудников.
Решение второй задачи «кажется» автору статьи неколько более важным.
Исходные данные
До конца дойти попробуй,
Сумей...
Теперь о скучном, поскольку автором все уже смакетировано, проверено, практические результаты получены. Для технической реализации коллективной работы с библиотекой взаимоувязанных документов в рамках компании потребуются технические и программные средства, о которых ниже.
Технические средства
Автором при макетировании использовалась машинка где–то 1999 года выпуска, на базе семисотмегагерцового селерона со 128 Мб оперативной памяти и винчестером около 8 Гб. Сетевая карта пятидолларовая, без встроенного процессора. Такого хлама в любой компании навалом, многие не знают, как от него избавиться. Автор коллекционирует динозавриков и использует оных для экспериментов: в качестве линуксовых маршрутизаторов и веб–серверов. Под 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, что позволит избежать ряда проблем вроде паразитного документооборота техдокументации.
