11.4 Заключение
Данная глава представляет систематизированный подход к разработке объектно-ориентированного проектирования с использованием UML. Тем не менее, была обсуждена лишь только главная часть проектирования. Из сценариев использования мы получили диаграммы классов и диаграммы последовательностей. Чтобы иметь полную модель системы, нам нужно будет добавить диаграммы активности, взаимодействия, состояний и топологии. Диаграммы сценариев были кратко упомянуты в Главе 7 «Создание Сценариев Использования (Use Cases)». Более детальное обсуждение проектирования с использованием UML выходит за рамки этой книги.
Данная глава показала, каким образом классы образуются от сценариев использования, и что сценарии предоставляют полноценный, структурированный подход к распределению поведения системы (операций) по определенным классам, позволяющий получить устойчивые и удобные в сопровождении системы. К сожалению, этот подход часто игнорируется, и многие организации используют для идентификации классов и операций несистематический, ситуативный «ad-hoc» подход, приводящий к низкокачественному дизайну.
С помощью спроектированной модели системы некоторые инструменты (такие как IBM Rational Rose и IBM Rational System Architect) позволяют Вам по частям генерировать код (или, по крайней мере, stub-код - использующий вызов удаленных процедур) в конечный язык программирования. Тем не менее, если даже Вы не используете модель для генерации кода, UML диаграммы помогают осуществлять эффективные коммуникации между дизайнерами, разработчиками, бизнес-аналитиками и другими членами команды.
Ссылки
BOO04] Booch, Grady, James Rumbaugh, and Ivar Jacobson. The Unified Modeling Language
Reference Manual, Second Edition, Boston: Addison-Wesley, 2004.
[BOO05] Booch, Grady, James Rumbaugh, and Ivar Jacobson. The Unified Modeling Language
User Guide, Second Edition, Boston: Addison-Wesley, 2005.
[IBM03c] Rational Rose User’s Guide, IBM Corporation, 2003.
Глава 12
Документация
Данная глава рассматривает документацию RequisitePro – доступные типы документации, существующие шаблоны в RequisitePro, а также как использовать IBM Rational SoDA для автоматической генерации отчетов. Прежде чем перейти к типам документации, предлагаемых RequisitePro, данная глава начинается с обсуждения основных существующих типов документации.
12.1 Типы Документации
Существует много способов классификации документации. Возможно, наиболее важный из них – классификация по аудитории, для которой предназначается документация:
Внутренняя документация для коммуникаций между членами команды.
Техническая документация для тех, кому может понадобиться оптимизация системы в будущем.
Пользовательская документация.
Маркетинговые материалы для потенциальных заказчиков.
Внутренняя Документация
Внутренняя документация используется на протяжении всего жизненного цикла проекта для коммуникаций между членами команды в процессе разработки системы. Некоторые документы данного типа могут быть также использованы для коммуникаций с пользователями (Спецификация Сценариев Использования - Use Case Specification) или как приложение к контракту заказчика (Концепция проекта – Vision).
Техническая Документация
Мы не можем рассчитывать на то, что когда понадобится оптимизация системы, мы сможем привлечь к этому изначальную команду разработчиков. Это означает, что вся система должна быть документально оформлена на различных уровнях (архитектура, дизайн, код). С помощью этой документации команда, вносящая изменения в систему, может легко понять, каким образом исправить ошибки или расширять функционал системы. Она может включать UML – диаграммы, описывающие дизайн системы, диаграммы отношений сущностей, показывающие схему базы данных, а также графические схемы, отображающие алгоритмы.
Одна из наиболее важных форм технической документации – это документация исходного кода. Для облегчения создания таких документов, многие инструменты могут генерировать документацию из кода, главным образом из комментариев, включенных в код. Сравнение некоторых таких инструментов может быть найдено тут: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators. Использование этих инструментов требует от разработчиков следовать некоторым указаниям по извлечению документации из кода. Преимущество в использовании таких генераторов кода в том, что документация может быть автоматически обновлена после изменений в самом коде. Тем не менее, довольно трудно добавлять текст в свободной форме в такие документы.
Пользовательская Документация
Пользовательская документация описывает, как пользоваться системой. Она может быть адресована пользователям, системным администраторам, персоналу справочной службы или группе по обслуживанию системы. Вместо печатной версии, некоторые документы могут быть доступны он-лайн в форме справки или руководства.
Пользовательская документация включает:
Руководства пользователей (User Guides).
Справочники (Reference materials).
Инструкции (Tutorials).
Руководства по установке (Tutorials).
Различные типы пользовательской документации могут иметь различную структуру. Справочники обычно имеют форму списка некоторых команд, функций или инструкций, отсортированных в алфавитном порядке. Руководства пользователя используют тематический подход – они содержат главы, которые фокусируются на определенной теме. Инструкции содержат пошаговое описание определенных задач [WIK06].
Пользовательская документация может также содержать описание программного интерфейса приложения, веб-сервисов или иных интерфейсов между системой и другими приложениями. В этом случае такой документ адресуется программистам, которые разрабатывают взаимодействующие с системой приложения.
Маркетинговые Материалы
Маркетинговая информация, обычно адресуемая потенциальным заказчикам и клиентам, описывает преимущества системы. Нет необходимости детально описывать, что система делает и каким образом она построена. Этот тип публикации включает в себя брошюры, листовки, таблицы и каталоги. Он также может быть опубликован в электронной форме, например в презентации Microsoft PowerPoint, веб-сайт или CD-демонстрации.
12.2 Документы в RequisitePro
В предыдущем пункте была описана классификация типов документов, чтобы показать, для каких типов документов RequisitePro наиболее полезен.
Большая часть документов, разрабатываемых с помощью RequisitePro, попадает в категорию внутренней документации. Все предустановленные шаблоны, предлагаемые в данном инструменте, относятся к документам, которые используются в течение процесса разработки программного обеспечения.
Иногда RequisitePro также используется для создания технической документации, особенно если один и тот же документ используется сначала в течение разработки, а затем хранится в качестве справочника после выпуска системы.
Некоторые документы, изначально созданные в процессе управления требованиями, позже могут быть использованы в пользовательской документации. Например, применение текста сценариев использования (use cases) в руководствах пользователей.
Гораздо реже RequisitePro используется для маркетинговых материалов. Маркетинговые брошюры обычно требуют сложного графического дизайна, а возможности графики RequisitePro ограничены функциональностью Microsoft Word.
Для создания документа в RequisitePro тип документа должен быть доступен в проекте. Какой тип документов уже добавлен в проект зависит от того, какой шаблон проекта был использован. Например, для шаблона Use Case (Сценариев Использования) типы документов по умолчанию следующие:
Словарь (Glossary).
План Управления Требованиями (Requirements Management Plan).
Запросы Заинтересованного Лица (Stakeholder Request).
Спецификация на Дополнительные Требования (Supplementary Requirements Specification).
Спецификация Сценариев Использования (Use Case Specification).
Концепция проекта (Vision).
Традиционный шаблон содержит Спецификацию Требований к Программному Обеспечению (Software Requirements Specification) вместо Сценариев Использования и Дополнительных Требований:
Словарь (Glossary).
План Управления Требованиями (Requirements Management Plan).
Спецификация Требований к Программному Обеспечению (Software Requirements Specification).
Запросы Заинтересованного Лица (Stakeholder Request).
Концепция проекта (Vision).
Чтобы увидеть, какой тип документов доступен в Вашем проекте, выполните следующие действия:
Нажмите правой кнопкой мышки на названии проекта и выберите Properties (Свойства).
Выберите закладку Document Types (Типы Документа), как показано на Рисунке 12.1.
Рисунок 12.1. Типы документов, доступные по умолчанию в шаблоне проекта Use Case (Сценариев Использования).
Создание Документа из Доступного Типа Документов
Если тип документа уже находится в проекте, то для создания документа выполните следующие действия:
Нажмите правой кнопкой мышки на папке, где Вы бы хотели создать документ.
Выберите New>Document (Новый>Документ).
Заполните диалоговое окно, как показано на Рисунке 12.2. Доступные типы документов находятся в списке внизу экрана.
Рисунок 12.2. Диалоговое окно Document Properties (Свойства Документа).
Добавление Нового Типа Документов
Если нужный тип документа отсутствует в проекте, добавьте его, выполнив следующие действия:
Выберите File>Properties (Файл>Свойства).
Нажмите на закладку Document Type (Тип Документа).
Нажмите Add (Добавить).
Заполните диалоговое окно, как показано на Рисунке 12.3.
Рисунок 12.3. Outlines (шаблоны), доступные в RequisitePro.
При добавлении документа Вам необходимо выбрать outline – шаблон, который будет использоваться для всех документов данного типа. В RequisitePro доступны следующие типы шаблонов:
Спецификация на Функциональные Тестовые Сценарии (Functional Test Case Specification).
• Усовершенствованная Спецификация Требований к Программному Обеспечению (Modern Software Requirement Specification).
• Спецификация Мульти-Сценариев Использования (Multi-Use Case Specification).
• Шаблон Требований Продукта (Product Requirements Outline).
• RUP Словарь Предметной Области (Rational Unified Process Business Glossary).
• RUP Бизнес Правила (Business Rules).
• RUP Спецификация на Реализацию Сценариев Использования Предметной Области (Business Use Case Realization Specification).
• RUP Спецификация Сценариев Использования Предметной Области (Business Use Case Specification).
• RUP Концепция Предметной Области (Business Vision Document).
• RUP Словарь (Glossary).
• RUP План Управления Требованиями (Requirements Management Plan).
• RUP Дополнительные Требования к Предметной Области (Supplementary Business Specification).
• RUP Спецификация Требований к Программному Обеспечению (Software Requirement Specification).
• RUP Спецификация Сценариев Использования Требований Программного Обеспечения (Use Case Software Requirement Specification).
• RUP Дополнительная Спецификация (Supplementary Specification).
• RUP Запросы Заинтересованного Лица (Stakeholder Requests).
• RUP План Тестирования (Test Plan).
• RUP Спецификация Сценариев Использования (Use Case Specification).
• RUP Концепция проекта (Vision Document).
• Требования к Программному Обеспечению (Software Requirements).
Создание Нового Типа Документов
Если Вы хотите создать документ, для которого нет соответствующего типа, Вам нужно создать новый тип документов и шаблон для этого типа. Этот процесс детально описан в Главе 9 «Создание Тестовых Сценариев (Test Cases) из Сценариев Использования (Use Cases)» в пункте 9.3.
Импорт Документа
Каждому документу назначается определенный тип. Даже если Вы импортируете документ из приложения вне RequisitePro (см. Главу 4 «Настройка Проекта» пункт 4.1), Вам все равно нужно определить тип для него. Если формат импортируемого документа не совпадает с выбранным типом документа, появляется сообщение с предупреждением, как показано на Рисунке 12.4. Нажатие на No (нет) оставляет оригинальный формат документа.
Рисунок
12.4. Сообщение
с предупреждением появляется, когда
импортируемый документ имеет формат,
отличный от выбранного типа документа.
12.3 Использование IMB Rational SoDA
IBM Rational SoDA (Software Documentation Automation) – это инструмент для документирования и генерации отчетов [IBM01]. Основное преимущество SoDA – это возможность извлекать информацию из остальных инструментов Rational (таких как RequisitePro Rational Rose). Большинство шаблонов отчетов уже предопределены. Вдобавок к этому, Вы можете настраивать существующие шаблоны или создавать новые, используя простой язык, состоящий из всего лишь четырех команд: Open (Открыть), Display (Отобразить), Repeat (Повторить) и Limit (Ограничить).
Разница между отчетами и документом в том, что отчет генерируется каждый раз с нуля, тогда как в процессе генерации документа пункты, добавленные вручную, остаются неизменными. Обновляется только информация, извлеченная из других инструментов.
Данный пункт показывает, как создавать отчет с использованием предустановленных шаблонов SoDA.
Генерация Отчета из RequisitePro
Если Вам необходим отчет относительно элементов проекта в RequisitePro, Вы можете создать его как из RequisitePro, так и из SoDA. Чтобы сделать это из RequisitePro (что гораздо проще и быстрее) выполните следующие действия:
Выберите Tools>Generate RequisitePro Report (Инструменты>Генерировать Отчет RequisitePro).
Выберите отчет из списка, как показано на Рисунке 12.5, и нажмите ОК.
Рисунок 12.4. Выбор отчета RequisitePro.
Рисунок 12.6. показывает примерный отчет, который содержит все документы и все требования.
Рисунок 12.6. Отчет RequisitePro, показывающий всю проектную документацию и требования.
Генерация Отчета из SoDa
Вы можете сгенерировать тот же самый отчет из SoDa, выполняя следующие действия:
Запустите Rational SoDA, выбрав All Programs>Rational Software>Rational SoDA for Microsoft Word (Все Программы>Rational Software>Rational SoDA для Microsoft Word). Откроется пустой документ Microsoft Word.
Выберите SoDA>Getting Started (Начало Работы).
Нажмите Next (Далее) в диалоговом окне, как показано на Рисунке 12.7.
Рисунок 12.7. Генерация предустановленного отчета с использованием SoDA: Шаг 1.
Выберите отчет, который вы хотите получить, например reqpro\docsreqts.doc (см. Рисунок 12.8), и нажмите кнопку Next (Далее).
Рисунок 12.8. Генерация предустановленного отчета с использованием SoDA: Шаг 2.
Нажмите кнопку Browse (Обзор), чтобы выбрать путь для сохранения файла, как показано на Рисунке 12.9).
Рисунок 12..9 Генерация предустановленного отчета с использованием SoDA: Шаг 3.
Нажмите кнопку Generate (Генерировать), как показано на Рисунке 12.10.
Рисунок 12.10. Генерация предустановленного отчета с использованием SoDA: Шаг 4.
В диалоговом окне Identify Project (Идентификация Проекта) нажмите кнопку Browse (Обзор), выберите файл .rqs, который содержит проект RequisitePro, и нажмите ОК (см. Рисунок 12.11).
По умолчанию проект расположен в директории C:\Program Files\Rational\
RequisitePro\Projects\project name.
Рисунок 12.11. Идентификация проекта, из которого будет генерироваться отчет.
Сгенерированный отчет должен выглядеть так же, как отчет, сгенерированный из RequisitePro (см. Рисунок 12.6).