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

Требования к системам разработки документации

На данный момент на рынке представлено достаточно большое количество ПО, позволяющего разрабатывать техническую документацию, в том числе в соответствии с требованиями S1000D. Конечно, не все эти программные продукты равнозначны по своим функциональным возможностям. Одни представляют собой простые редакторы, другие — клиент-серверные системы, обеспечивающие распределенную разработку документации, хранение и управление репозиторием объектов, используемых при разработке; управление доступом, публикацией и другими полезными функциями.

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

На наш взгляд основными из подобных характеристик являются:

• — как это не кажется очевидным, но все же — это поддержка стандартов;
• — наличие графического интерфейса редактора модулей данных, обеспечивающий ввод и форматирование текста в соответствии с S1000D, вставку различных графических объектов (2D, 3D, мультимедиа);
• — функция формирования и управления PM, DMRL;
• — возможность публикации документа (информационного набора), как для автономного просмотра, так и для размещения в интернет с возможностью работы с документом посредством стандартного браузера ОС;
• — возможность вывода документа на печать. Причем полученный бумажный документ, так же должен отвечать действующим стандартам;
• — наличие функций для управления доступом к объектам CSDB;
• — ведение нескольких SNS, автоматизированное назначение кода;
• — распределенная разработка документации в клиент-серверной среде;
• — желательно наличие функций планирования работ и управления процессами разработки документации (workflow) [10, c.92].

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

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

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

Итак, целями автоматизации разработки являются:

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

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

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

для исключения возможных формальных претензий со стороны заказчика.

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

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

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

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

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

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

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

отсутствием интереса к процессу разработки (и т. д.) техдокументации.

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

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

техническая документация на автоматизированные системы;

техническая документация на изделия;

техдокументация на программные изделия — программная документация.

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

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

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

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

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

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

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

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

стили заголовков с многоуровневой нумерацией — особо продвинутыми пользователями (крайне редко);

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

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

Так ведь и претензии предъявить нельзя! У того же проджект-менеджера основная задача — не владение Вордом на уровне продвинутого пользователя, а получение подписи заказчика на Акте приемки-сдачи работ. Мотивация, пардон, отсутствует.

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

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

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

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

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

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

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

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

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

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