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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• процесс разработки технической документации;

• процесс публикации технической документации как на бумажных носителях, так и в электронном виде;

• процессы учета и хранения технической документации;

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

• процесс обмена технической документацией между подразделениями компании;

• процесс передачи технической документации заказчику (или конечному пользователю).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• замечательные особенности советской нормативно-технической документации.

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

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

 Электронная техническая документация хранится в едином централизованном хранилище – в базе данных. AuthorIT позволяет применять в качестве базы данных как MS SQL, так и отдельные файлы библиотек. А вот MySQL, увы, пока не позволяет.

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

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

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

• подсистему Authoring;

• подсистему Importer;

• подсистему Publisher;

• подсистему Project Manager;

• подсистему Administration.

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

    Подсистема Importer обеспечивает возможность импорта документов из файлов различных форматов (включая *.doc и *.htm) с сохранением структуры и содержания разделов документа во внутреннем формате AuthorIT.

    Есть нюансы: попытка импорта неправильно структурированного вордовского документа не пройдет. Особенно, если такой файл содержит кучу OLE-объектов и сложные колонтитулы.

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

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

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

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

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

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

Автоматизация оформления документации

    Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.
     Описание должно было в себя включать:

• Планы разработки ПО

• Требования к ПО

• Описание реализации требований к ПО

• Таблицы трассируемости(соответствия) требований к ПО и реализации

• Описание тестов на ПО (Примеры и процедуры верификации ПО)

• Таблицы трассируемости(соответствия) требований к ПО и тестов

• Отчет об обнаруженных проблемах

• Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)

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

​

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

    Таблицы в формате CSV удобно редактировать в табличном процессоре. Данные о проекте (текущую версию, наименование, совместимое оборудование) хранил в формате XML.

    Описание реализации требований уже содержится в doxygen комментариях к исходному коду. Doxygen специально для таких случаев может генерировать документацию в формате XML.

    Генератор документации на основе шаблонов документов создает LaTeX документы, которые уже в PDF формате передаются заказчику

​

Генератор документации

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

Скрипт сборки я реализовал в Makefile. Скрипт выполнял следующие действия:

• Получал исходники

• Генерировал XML описания с помощью Doxygen

• Собирал все необходимые документы из шаблонов с помощью pytemplate.py

• Генерировал PDF-ки LaTeX-ом

• Формировал дерево папок и создавал образ диска для записи

• формировал необходимую сопроводительную документацию (файл с титульными листами, этикетку диска)​

    Ключевой элемент системы — утилита обработки шаблонов документов.
 

Утилита обработки шаблонов

    Исходные коды можно получить: github.com/krotos139/pytemplate

    Или установить утилиту можно с помощью команды:

    sudo pip install pytemplateproc

    Использование утилиты: pytemplate.py [options]
    Опции:

• --version Отобразить версию

• -h, --help Отобразить информацию о ключах запуска

• -t TEMPLATE, --template=TEMPLATE Указать путь до файла шаблона

• -o OUTPUT, --output=OUTPUT Указать путь до выходного файла

• -f FORMAT, --format=FORMAT Формат файла шаблона, может принимать значения (odt и text)

• -a ARG, --arg=ARG Дополнительная сущность для шаблона

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

    Поддерживаемые источники данных:

• CSV таблица (Может быть отредактирована в Exel при соблюдении определенных правил)

• XML документ

• Текстовый файл

• SQLite база данных

• Функция MD5 от файла

• Функция получения данных о файле

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

Заключение

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

​