Читайте также статьи и материалы о технологиях Rational и Microsoft в блоге Новичкова Александра и Шамрая Александра

Формирование проектной документации с использованием IBM Rational SoDA. Практика использования.

Автор: Новичков Александр

Введение

SoDA (Software Documentation Automation), оригинальная разработка компании Rational, су-щественно упрощающая процесс создания проектной документации и поддержания актуальности последней в течение всего цикла разработки ПО.

Ведь не для кого не секрет, что у любого сотрудника компании уходит достаточно большое количество рабочего времени на написание всевозможных отчетов. Как показывает статистика, из 8 часов рабочего дня на документирование тратится 1 час... То есть к концу недели мы получаем 5-6 часов «потерянного» времени. Слово «потерянного» я не случайно взял в кавычки, поскольку руко-водство проекта и заказчики всегда хотят быть в курсе происходящих событий в проекте, за кото-рый они платят деньги. Это одна сторона медали – сторона руководящего звена. Психология же разработчиков выглядит (мягко говоря) несколько по другому – им не интересно составлять отчеты, тем более когда требуется составлять читаемые отчеты – понятные не только самому писателю.

Согласитесь, ситуация достаточно типична для всех компаний, связанных с разработкой! И кажется, что из данного порочного круга нет выхода. С появлением технологий Rational это уже не актуально, поскольку программные продукты, составляющие оптимальные решения для каждого этапа в разработке ПО, закрывают собой все существующие бреши и несогласованности в разработ-ках. Некоторые из продуктов мы уже рассматривали на страницах КомпьютерПресс’а (в частности, статьи по ClearCase – средству конфигурационного управления, средствам тестирования для разра-ботчиков, и, наконец, ClearQuest – средство управления изменениями), но все рассматриваемые продукты касались только «кухни» проекта. Данные, полученные в результате работы описанных программ, могут относиться к коммерческой тайне и, в связи с этим, не подлежать разглашению. Даже заказчик системы, порой, не владеет всей «кухней» разработки. Но общаться с заказчиком (а равно как и с собственным руководством) надо. И надо общаться не на компьютерном сленге, а на языке понятном всем окружающим, не зависимо от их степени познания ИТ. Заказчику надо демон-стрировать технические задания, планы работ, описания системы... и так далее. Это лишь малая толика проблем, связанных с отчетностью, которые позволит решить SoDA. Можно, правда, возра-зить, что, уже есть средства отчетности наподобие CrystalReports и схожих с ним, выдвинуть гипо-тезу о том, что не нужен еще один инструмент, выполняющий аналогичные функции. Спешу разве-ять миф – это не так - SoDA является уникальным продуктом, не подменяющим не один из уважае-мых средств отчетности. Она стоит особняком от обычных средств документирования и отчетности, поскольку позволяет то, что другим не под силу. Но об этом чуть позже...

Хочется во введении также коснуться таких тем как управление качеством и выработка кор-поративного стандарта. Любой документ, любая бумага, любое слово в компании, должно быть стандартизовано, то есть компания должна выработать свой корпоративный стандарт на разные эта-пы разработки ПО (если это касается софтверной компании). Разрешение всех этих проектных ню-ансов, связанных со стратегией выработки концепций содержатся в продукте Rational, носящим имя Rational Unified Process, который и позволит основываясь на опыте многих крупных компаний-разработчиков программного обеспечения, выстроить выпуск собственного ПО наиболее пра-вильным способом. Здесь я не буду вдаваться в дебри RUP, а отошлю читателей к специальным книгам и статьям, где данная тема подробно изложена. Давайте вырвем из всего производственного процесса только документирование и отчетность, и попробуем понять, что дает SoDA в данном из-ложении.

Итак, компании надо иметь некий стандарт на отчетность для внутренних целей (как говори-лось уже выше) и для объяснения с заказчиком. Сейчас, как известно, на софтверном рынке очень много подрядчиков и не очень много заказчиков, платящих деньги за работу. А те которые и есть не спешат доверять свои заказы и деньги первой встречной компании, которая декларирует 100% ис-полнение заказа. В нынешних условиях мерилом зрелости компании уже является даже не ее статус на рынке разработок, а уровень CMM (Capability Maturity Model - модель зрелости процессов созда-ния ПО), который ей присвоен. Получение уже второго уровня софтверной компанией, гарантирует приток инвестиций со стороны заказчиков, поскольку, данный уровень не на словах, а на деле га-рантирует исполнение заказа в срок и без превышения бюджета. Но если СММ только развивается, то сейчас вовсю «шагают» по стране такие стандарты как ISO так и отечественные ГОСТы на раз-работку и документирование. И во всех этих стандартах уделяется большое внимание документиро-ванию и отчетности.

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

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

Хочется отметить еще одну особенность использования автоматизированной отчетности – при таком подходе мы практически избавляемся от типичных во все времена вопросов: «…где по-следняя версия документа?», «…почему версии документов не совпадают?» и так далее. С исполь-зованием SoDA подобных вопросов не может быть в принципе, так как все документы выпускаются автоматически, а данные берутся из инструментальных средств IBM Rational.

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

Что такое SoDA?

SoDA (Software Documentation Automation) – макрос, написанный для MS Word существенно упрощающая процесс создания проектной документации и поддержания актуальности последней в течение всего цикла разработки ПО.
SoDA особенно полезна при реализации крупных информационных проектов, в которых на составление документации и ее постоянную переработку часто тратится очень много времени и сил разработчиков.

По задаваемым пользователем шаблонам SoDA "компилирует" документацию, собирая в один документ текстовые и графические данные из различных источников, например из моделей, созданных в Rational Rose. Далее пользователь может отредактировать полученный документ по-средством Microsoft Word или Adobe FrameMaker+SGML.
SoDA сама по себе очень зависимый продукт, поскольку, как система отчетности, она базиру-ется на тех данных, которые получает из сторонних программ.
SoDA поддерживает всю линейку продуктов Rational Software, позволяя тем самым создавать сложные комбинированные отчеты, базируясь на выходных данных программ состава Rational Suite. Плюс ко всему она имеет доступ к данным из MS Project.
Из основных возможностей следует отметить:

• Документирование всех этапов работы над проектом;
• Базируясь на шаблонах, IBM Rational SoDA поддерживает возможность стандартиза-ции типов документов в рамках проекта или стандартов компании. IBM Rational SoDA может обеспечить соответствие проектной документации таким международ-ным стандартам, как ISO, SEI CMM, IEEE, а также отечественным серии ГОСТ 19 и 34;
• IBM Rational SoDA содержит более 70 шаблонов отчетов;
• Для создания шаблонов документов IBM Rational SoDA предлагает простой в ис-пользовании, интуитивно понятный графический язык;
• Шаблоны IBM Rational SoDA содержат информацию о формате документа, о его сти-ле и структуре, определяют расположение источника и элементов информации, кото-рые следует извлечь из хранилищ других инструментов IBM Rational;
• IBM Rational SoDA использует наиболее популярные средства подготовки докумен-тации – Microsoft Word и Adobe FrameMaker+SGML, что упрощает его освоение;
• IBM Rational SoDA может автоматически генерировать документы и отчеты в форма-те HTML, что позволяет создать информационный портал для участников проекта, где можно будет видеть текущее состояние проекта по его документам и отчетам. Подобный подход особенно полезен для объединения географически распределенных групп или групп, работающих на различных платформах;
• IBM Rational SoDA осуществляет сбор информации из многочисленных и разнород-ных источников, а также поддерживает русскоязычные шаблоны документов и отче-тов, что позволяет использовать ее для получении практически любых отчетов или документов. Нами разработана методика по которой возможна генерация документов по ГОСТ серии 34 и 19;
• Автоматическое извлечение информации из файлов, созданных различными инстру-ментальными средствами. IBM Rational SoDA "понимает", структуру информации, хранимой теми системами, с которыми она интегрирована, а сама информация дос-тупна ей через API этих систем;
• Сохранение при "перекомпиляции" текста и графики, введенных пользователем вручную в текстовом процессоре. Если пользователь, скажем, в Microsoft Word, до-бавил какие-нибудь комментарии или иллюстрации в сгенерированный с помощью SoDA документ, то перестраивая данный документ снова, IBM Rational SoDA его не "испортит";
• Частичная "перекомпиляция" больших документов. Проектная документация к масштабным программным системам может достигать гигантских объемов. Поэтому в IBM Rational SoDA предусмотрена возможность "перекомпилировать" только те части документации, которые действительно утратили актуальность;
• Сбор информации из многочисленных и разнородных источников.
  

Формирование отчетов и документов возможно как в формате Word, так и в формате HTML. Преимущество подхода в генерации документа: единый центр хранения актуальной информации, отсутствие в проектной команде классического вопроса: "а где та версия документа, которую мы отдавали заказчику?" - SoDA хранит историю версий разделов и способно выпустить контент документа по состоянию на указанный момент времени.

Работа в SoDA

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

SoDA поддерживает соответствие между документом и источником (источниками) через процесс, названный Intelligent Document MergingTM (IDM). Если удалить объект из домена источ-ника (например, класс в Rose) SoDA удалит соответствующие секции из документа, генерируемые из этого домена. Если добавить в источник объект SoDA создаст новую секцию в нужном месте документа.

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

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

При создании документа SoDA, выполняя команды шаблона, просматривает информацию документа. При этом в зависимости от типа выполняемых команд производятся необходимые дей-ствия над документом:

• SoDA использует аргументы каждой из команд OPEN для создания указателей на отдель-ные объекты в выбранном домене – источнике;
• Для каждого объекта, полученного командой REPEAT, создается секция, в которую зано-сится команда связи. (Термин «Секция» может означать параграф, элемент списка, или любую группу имен, следующих через запятую). Команда связи обращается только к од-ному объекту, который соответствует новой секции, и используется для обращения к ис-точнику (Visit Source) и регенерации документа. Секция, которая включает в себя от-дельную команду связи, остается в документе, но скрытно;
• Когда команда DISPLAY выберет значение, специфицированное в команде связи, это зна-чение занесется в документ;
• Команда LIMIT либо выбирает новую секцию либо ее пропускает. Если объект существует и отвечает условиям выбора секция создается и команда LIMIT остается в документе иг-рая роль, подобную команде связи. В противном случае команда остается в документе, но не видна. При каждом обновлении документа команды LIMIT снова проверяют - не изменились ли характеристики объектов.
  

Генерация отчетов

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

При генерации отчета SoDA, выполняя команды шаблона, просматривает информацию источников, определенных в шаблоне и добавляет в отчет текстовую и графическую информацию в соответствии с указаниями выполняемых из шаблона команд:

SoDA использует аргументы каждой из команд OPEN для создания указателей на отдельные объекты заданного домена – источнике.

Для каждого объекта, полученного командой REPEAT, создается секция. (Термин «Секция» может означать параграф, элемент списка, или любую группу имен, следующих через запятую). Секция, которая включает в себя отдельную команду REPEAT, не копируется в отчет.

Команда DISPLAY выбирает значение в соответствии с установкой и записывает его в отчет.

Команда LIMIT либо разрешает обработку следующей секции, либо нет. Если объект создан и его характеристики удовлетворяют условиям, секция формируется. В противном случае перенос данных секции в отчет запрещается.

Шаблоны

Шаблон – это файл формата Win Word (. DOC формат), определяющий состав и структуру документа или отчета.

Он определяет:

• состав и структуру отчета /документа;
• состав объектов - источников информации и;
• состав их атрибутов, значения которых будут
  перенесены в отчет /документ.

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

Шаблон состоит из текста, и графики, переносимых в отчеты и документы без изменения, и команд SoDA , при помощи которых данные, заносимые в отчеты и документы, выбирается информационных источников, сформированных инструментальными средствами Rational Rose .

Характеристики всех информационных источников представлены в схемах доменов источников. Схема содержит данные обо всех объектах домена и их взаимных связях.

Описания схем доменов источников базируются на объектно-ориентированном подходе.

Что такое домены?

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

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

Как работать?

SoDA способна работать со следующими типами отчетов:

Встроенные в инструмент. С этой категорией все ясно. Здесь содержатся все необходимые отчеты при работе по технологии RUP

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

Существует масса способов формирования шаблонов. Из классических – берется англоязычный РУПовский шаблон и на его основе делается перевод. Для продвинутых вто-рой способ – шаблон формируется с нуля под собственную организацию. Третий способ более ред-кий, дорогой, но самый эффективный – пригласить консультантов, которые поставят процессы и сформируют нужный пакет автоматизированных отчетов.

Давайте немного остановимся на первом способе, когда за основу берется стандартный шаб-лон. Известно, что Rational не только полностью описала процесс выпуска программного обеспече-ния, но и создала программное обеспечение для каждого этапа. Соответственно, каждый продукт сохраняет данные, а SoDA по ним строит, или, как говорилось выше, компилирует отчет.
Если внимательнее присмотреться к этапам разработки по-Rational’овски, то получится вот такая картина:

1. Бизнес моделирование
2. Определение требований
3. Анализ и проектирование
4. Тестирование
5. Конфигурационное управление
6. Реализация
7. Развертывание
8. Внедрение

Естественно, каждый этап детально описан и подразумевает получение документа строго оп-ределенного образца (по RUP), после того как соответствующие данные были обработаны той или иной программой из набора средств Rational.
Скажем, на первом этапе, при помощи SoDA можно получить такие документы как: «Оценка организации заказчика», «Словарь терминов предметной области», «Коммерческое предло-жение», «Бизнес правила»... и так далее...
На втором этапе можно получить документы «Спецификация на программную систему» «Спецификация на функции системы»...
Каждый из этих отчетов будет соответствовать RUP, а форма изложения пересекаться с ISO. Далее его можно будет нести на согласование с заказчиком. Обратите внимание, первый этап назы-вается «БизнесМоделирование», что подразумевает использование на данном этапе средств визу-ального проектирования. По технологии RUP это Rational Rose, которая на основе различных диа-грамм позволит получить полную бизнес-модель предприятия и модель проектируемой системы. Соответственно, опять же по технологии RUP, на этапе проектирования, аналитик или проектиров-щик не только рисуют модель, создавая определенные связи между диаграммами, но и комменти-руют каждое свое движение в специальных полях, либо подключая уже имеющиеся документы к модели. Разумеется, что после всех возможных моделирований, получается отличная модель, пол-ностью описывающая бизнес процессы и программную систему. Но понятной она будет только уз-кому кругу лиц, владеющих полной картиной сделанного. Но заказчик зачастую плохо ориентиру-ется в мире диаграмм... Вот и настал черед SoDA! Из меню Rose запускается данный составитель отчетов, пользователь выбирает тип отчета... и... через 1-5 минут на выходе получается готовый до-кумент с разметками, комментариями и фрагментами моделей в формате Word. Причем, все оформ-ляется в виде внедренных объектов, а это значит, что изменения, внесенные в модель автоматически отражаются на документе.
Теперь давайте подробнее остановимся на том с какими программными продуктами работает SoDA и какие отчеты может выдавать:

Для тех, кто не знаком с терминологией приведем расшифровку типов отчетов

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

Тестировщики же смогут генерировать отчеты по всем ошибкам (дефектам) и представлять в удобной форме.

Не остались в стороне и разработчики. Для них будет полезным отчет по классам, когда в наглядном виде можно получить список классов с иерархией и описанием всех аттрибутов и мето-дов не выходя из среды разработки. В качестве одного дополнительного, я даже сказал бы, ком-плексного штриха, можно с помощью только Rose и SoDA сделать отчет по классам той системы, которая УЖЕ написана и скомпилирована! Rose имеет механизм так называемого обратного проек-тирования, когда исходный код превращается в модель Rose (преображаясь, в UML нотацию). При обратном проектировании учитываются все составляющие классов, а также комментарии, которыми они снабжались, и, соответственно, на выходе этой работы получается полная модель всех классов (с иерархией). После получения модели становится достаточно просто пропустить ее через систему генерации отчетов и получить полноценный документ, описывающий систему классов программно-го продукта по всем мыслимым и не мыслимым стандартам и правилам!

Естественно, на выходе для заказчика трудно получить 100% читаемый отчет. Но свои 80% SoDA честно сгенерирует. Остальную косметическую правку можно возложить на плечи техниче-ского писателя, дабы придать отчету (на этом этапе уже – документу) помпезно-литературный вид.

А как это работает на практике?

Давайте рассмотрим на практику создание своего шаблона с НУЛЯ в схематичном виде по шагам:1.

1. Сформировать текст в MS Word. Имеется ввиду простой текст, который является постоянным (например, наименования разделов, их стиль, оглавление, итд). Он и будет являться шаблоном. Любопытно, что SoDA понимает и повторяет сама все конструкции MS Word: ссылки, таблицы, картинки...
2. Вызвать SoDA и в нужных местах документа поставить вызов доменов. Для этого используется модуль Template View
3. Используя команды OPEN - для доступа к репозиторию, REPEAT - для выбора данных и DISPLAY - для их отображения в теле отчета - создаем сценарий
4. Запускаем не генерацию
5. Получаем готовый документ
   

Ниже представленны скриншоты, демонстрирующие последовательность действий.

Взят за образец документ - описание системы. Рисунок показывает начальный вид документа. Раздел "Назначение" и ряд других разделов генерируются автоматически. Наименования "master", "display"... есть визуальное отображение команд SoDA в теле документа.

SoDA интегрируется в верхнее меню MS Word, либо в инструментальнуую панель

Это режим Template View, в котором и формируется сам шаблон. Здесь оговариваются из каких источников берутся данные и как они отображаются

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

Заключение

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

Будучи частью платформы Team Unifying Platform во всех решениях IBM Rational Suite, IBM Rational SoDA представляет собой инструмент автоматизации документирования в масштабе всего проекта. Тесная интеграция с другими средствами IBM Rational делает SoDA идеальным инструментом для обеспечения необходимого уровня качества такой документации, как, например, оценка требований и проекта, критический разбор программы и тестовое покрытие.

И напоследок - основные преимущества представленной технологии:

• Централизованное внесение изменений. Все данные хранятся в едином центре. Документы генерируются по мере необходимости;
• Ведение истории изменений. Всегда видно кто и когда изменил раздел документа и для чего;
• Сбор информации из всех репозиториев программных продуктов IBM Rational;
• Сопровождение разделов документов дополнительными атрибутами;
• Минимизация ручных операций при выпуске документов. Снижение человеческого фактора;
• Осуществление контроля хода проекта по документации;
• Гибкая адаптация под любые стандарты. Шаблоны - это не только встроенные в RUP, но и любые другие от международных стандартов до внутрикорпоративных;
• Повторное использование в других проектах. Шаблон пишется один раз для одного проекта и применяется во всех остальных, где он будет востребован.
  

Продолжение следует

Читайте в следующей части:

• Примеры реальных шаблонов
• Практикум формирование шаблонов произвольного образца
• Как сделать так, чтобы SoDA правильно отображала таблицы

18.02.2008

Комментарии

• 
  Автор:   ·  14.08.2011 04:42:08
  If you are willing to buy a car, you would have to receive the personal loans. Moreover, my mother usually takes a credit loan, which occurs to be really reliable.
• 
  Автор:   ·  14.08.2011 02:47:04
  Specialists argue that loans help people to live their own way, because they are able to feel free to buy necessary stuff. Moreover, banks give consolidation loan for all people.
• jsxLVFUUlrSQ
  Автор: wTtKqI , [url=http://thbuxjxjiljx.com/]thbuxjxjiljx[/url], [link=http://nevstnfkqqtl.com/]nevstnfkqqtl[/link], http://ozrwwjuadohw.com/  ·  12.07.2011 16:55:36
  wTtKqI , [url=http://thbuxjxjiljx.com/]thbuxjxjiljx[/url], [link=http://nevstnfkqqtl.com/]nevstnfkqqtl[/link], http://ozrwwjuadohw.com/
• eyIdDIDpparOFX
  Автор: RdcNZQ rvhiptttjsfj  ·  11.07.2011 14:10:36
  RdcNZQ rvhiptttjsfj
• GBegwxbQWnEMLOoDda
  Автор: TPHrxl , [url=http://wiubobwimwlm.com/]wiubobwimwlm[/url], [link=http://pitpactthpqc.com/]pitpactthpqc[/link], http://dsoyamgmxgyp.com/  ·  10.07.2011 14:38:14
  TPHrxl , [url=http://wiubobwimwlm.com/]wiubobwimwlm[/url], [link=http://pitpactthpqc.com/]pitpactthpqc[/link], http://dsoyamgmxgyp.com/
• RdbrtUbvdCYEvrrAp
  Автор: WhmXqL wwxpsfsolkwr  ·  10.07.2011 10:31:48
  WhmXqL wwxpsfsolkwr
• bhhDkRvpopYadalQQW
  Автор: Haha. I woke up down today. YouВ’ve cheeerd me up!  ·  09.07.2011 17:48:35
  Haha. I woke up down today. YouВ’ve cheeerd me up!

Добавить комментарий (анонимные комментарии не публикуются!!!)

ФИО:
E-mail:
Тема:
Комментарий:
Оценка:
Код подтверждения:

Читайте также статьи и материалы о технологиях Rational и Microsoft в блоге Новичкова Александра и Шамрая Александра

Новости и пресс-релизы СМ-Консалт

Архив "Новости и пресс-релизы СМ-Консалт"