Лекция 24
Тема: Автоматизация разработки технической документации.
Цель: изучить процесс автоматизации разработки технической документации
Процессы разработки (сопровождения и т.д.) технической документации всегда и везде идут плечом к плечу с процессами разработки изделий, программных изделий, создания автоматизированных систем. В крупных организациях в процессе разработки техдокументации задействовано, как правило, значительное число специалистов различных подразделений. В мелких и средних компаниях техническая документация «составляется» «узким кругом ограниченных лиц», именующих себя техническими писателями (техписами) - представителями профессии, по сей день не нашедшей себе достойного места в общероссийском классификаторе.
Как бы то ни было, для большинства компаний разного калибра процесс разработки (сопровождения и т.д.) техдокументации остается занятием в немалой степени рутинным, трудоемким и ресурсоемким и, как правило, неблагодарным по отношению к непосредственным исполнителям.
Речь пойдет об автоматизации разработки (сопровождения и т.д.) технической документации для автоматизированных систем. Итак, целями автоматизации разработки являются:
повышение управляемости жизненного цикла техдокументации;
снижение трудоемкости и ресурсоемкости процессов жизненного цикла технической документации.
Задачи:
показать взаимосвязь документов (а также разделов, подразделов, пунктов, подпунктов и т.д.), входящих в состав техдокументации, разрабатываемой на стадиях и этапах создания автоматизированных систем;
дать практические рекомендации по автоматизации процессов жизненного цикла технической документации.
Техническая документация: ее назначение (и отношение к ней)
В компаниях, чья продукция может повлечь за собой гибель людей или нанесение серьезного материального ущерба, к составу и содержанию техдокументации относятся более или менее ответственно, помня о прокуроре. Таким образом, техдокументация в указанных компаниях, разрабатывается, как минимум:
во избежание ответственности перед законом - на авиажаргоне такой подход называется «прикрытием задней полусферы»;
для исключения возможных формальных претензий со стороны заказчика.
Указанный подход обеспечивает все предпосылки к разработке технической документации высочайшего качества. Ясно, что нести судебную ответственность и выплачивать денежную компенсацию за гибель животного американке, выстиравшей свою кошку в стиральной машине и высушившей любимицу в микроволновой печи, - дураков нет. Требуются лишь усилия разработчиков-профессионалов, помноженные на реализацию ими требований государственных стандартов.
Классикой жанра можно считать образцы эксплуатационной документации, разработанной советской оборонкой для Военно-Воздушных Сил. Точность, согласованность и уровень детализации документов был таков, что гарному хлопцу из отдаленного горного аула, призванному на срочную службу и едва читающему по-русски, можно было доверить выполнение ряда довольно ответственных операций при проведении регламентных работ на авиационной технике.
Но, как это ни печально, до сих пор многие г-да «эффективные менеджеры» (в погоне за длинным баксом) считают расходы на подразделения, занятые разработкой (сопровождением и т.д.) техдокументации, бессмысленными издержками. Г-да руководители - карающий меч прокуратуры снесет, в первую очередь, ваши головы, поскольку именно вы ставите на документах утверждающую подпись. А разработчик ни за что не отвечает.
В компаниях, выпускающих продукцию для «дома и офиса», состав, содержание и содержимое техдокументации мало кому интересны. Приоритеты иные. Для таких компаний главное, чтобы техдокументация была оформлена ярко и затейливо, выделялась на общем фоне и привлекала к себе внимание любителей фантиков. А еще лучше - в виде комиксов, поскольку все идет к тому, что публика скоро окончательно разучится читать.
Примеры, по мнению автора, приводить бессмысленно. Многие неоднократно сталкивались и сталкиваются с совершенно бестолковой, размазанной, как манная каша по тарелке, писаниной. Писаниной, изданной в красочной суперобложке, на глянцевой бумаге. С глоссарием. С индексом. Сверстанной по «законам восприятия». И бесполезной в плане содержания. Usability в вульгарном, а не ГОСТовском смысле.
Тем не менее и компании-акулы, и мелкие любители национальной рыбалки в мутной водичке отечественного бизнеса едины в своем отношении к техдокументации, как минимум:
вынужденным осознанием факта, что техническая документация должна быть;
отсутствием интереса к процессу разработки (и т.д.) техдокументации.
С отношением и назначением покончено, теперь коротко о составе технической документации.
Техническая документация: состав
В серьезных компаниях, работающих на рынке автоматизированных систем, поставляемых солидным заказчикам, в состав техдокументации входят:
техническая документация на автоматизированные системы;
техническая документация на изделия;
техдокументация на программные изделия - программная документация.
Следует отметить, что разработка технической документации на автоматизированные системы в современных условиях неумолимо влечет за собой разработку техдокументации на изделия и программные изделия, за исключением покупных.
С другой стороны, все, что производится в современых условиях, проявляет все больше и больше признаков автоматизированных систем. Мобильный телефон, к примеру, трудно назвать изделием в классическом понимании. Вот ведро или лом - это точно изделия, и ничего больше. Тот же FineReader™ можно назвать программным изделием только на дистрибутивном носителе. После инсталляции FineReader начинает автоматически распознавать тексты - становится (в совокупности с программным и техническим обеспечением (средствами ПЭВМ) полноценной автоматизированной системой или системой обработки информации.
Техническая документация: жизненный цикл
Как бы то ни было, кто бы ни занимался разработкой техдокументации, каков бы ни был ее состав, обладает техническая документация, как и все в этом мире, собственным жизненным циклом. До слез понятно, даже без ссылок на всевозможные стандарты, что жизненный цикл техдокументации включает в себя, как минимум:
процесс разработки технической документации;
процесс публикации техдокументации как на бумажных носителях, так и в электронном виде;
процессы учета и хранения технической документации;
процессы модификации, отслеживания изменений техдокументации - сопровождения;
процесс обмена технической документацией между подразделениями компании;
процесс передачи техдокументации заказчику (или конечному пользователю).
При разработке и публикации техдокументации применяются различные текстовые и графические редакторы различных производителей и версий. Пишут все. Сохраняют файлы все. Печатают все. Никакими санкциями, никакими корпоративными стандартами преодолеть склонность россиянина к анархии невозможно. Каждый пользуется тем, что привычней. Как следствие, форматы файлов, стили оформления технической документации трудно назвать единообразными и соответствующими требованиям стандартов. У каждого индивидуума свои предпочтения (в шрифтах, отступах и прочей разметке).
Еще одна общая беда - электронная техническая документация не структурируется должным образом. Для разбиения электронной техдокументации на элементы данных - разделы, подразделы, пункты, подпункты - применяются:
стили заголовков с многоуровневой нумерацией - особо продвинутыми пользователями (крайне редко);
нумерованные списки – ворд достаточно «умен» и при попытках ручного ввода нумерации разделов иногда пытается автоматически разбить сплошной текст на разделы и подразделы в виде нумерованных списков;
выделение строки абзацного текста жирным и ручной ввод номера раздела – лишь бы на бумаге все выглядело «изячно», если угодно - «элегантно».
Так ведь и претензии предъявить нельзя! У того же проджект-менеджера основная задача - не владение вордом на уровне продвинутого пользователя, а получение подписи заказчика на Акте приемки-сдачи работ. Мотивация, пардон, отсутствует.
О хранении - электронная техдокументация хранится в структуре каталогов пользовательских компьютеров и серверов. Естественно, абы как. Российский менталитет-с. Структура пользовательских каталогов хаотична. Где что лежит - в лучшем случае вспомнит лишь хозяин. Названия файлов электронной технической документации также не отличаются единообразием и удобочитаемостью. Резервное копирование файлов электронной техдокументации, как правило, не производится, что приводит к утрате документов.
Об учете - попытки поставить классический учет бумажных документов терпит фиаско. Уследить за всеми участниками процесса разработки нереально. Время заказ-нарядов на машинописные работы давным-давно прошло. Быстро не «только кошки плодятся», но и документация. И также «промискуитетно».
О сопровождении техдокументации - при больших объемах своевременое внесение изменений в ряд отдельных документов, отслеживание актуальных версий, архивирование старых версий технической документации невозможны. Утрачивается согласованность (непротиворечивость) техдокументации.
Об обмене технической документацией внутри компании. Затребовали - отправил документ электронной почтой или показал, в каком каталоге сетевого диска документ хранится. Позднее внес в документ изменения. Не затребовали - не передал. Сбросить на расшаренный сетевой диск или на svn поленился, решил отложить на завтра - и благополучно обо всем забыл.
А документ, тем временем, отправляется затребовавшим подразделением в типографию, для тиражирования в количестве двух тысяч экземпляров и незамедлительной отправки заказчику.
Техническая документация: предпосылки к автоматизации процессов жизненного цикла
Каковы же предпосылки к автоматизации процессов жизненного цикла технической документации? Вот они:
доступность специализированных средств разработки текстовых документов, построенных на основе концепции единого источника (исходника - single source) с возможностью многократного повторного использования текстов, графики, мультимедиа, гиперссылок и т.д.;
замечательные особенности советской нормативно-технической документации.
Специализированные средства разработки технической документации
Специализированных средств разработки технической (да и любой документации) навалом. Производятся таковые как отечественными компаниями, так и буржуйскими. Средства известные, на слуху, подробно останавливаться и приводить сравнительный анализ особого смысла нет. Предпочтения автора сводятся к применению при разработке (сопровождении и т.д.) техдокументации программы AuthorIT от AuthorIT Software Corporation Ltd.
12 818
3 063 
