18

ПКШ КЛР/ДЗ (ТЗ) (ООП) – Большаков С.А. 2013/2014 1-й курс

Методические указания к лабораторной работе № 13 по курсу

Программирование на основе классов и шаблонов

" Комплексная Лабораторная работа/Домашнее задание.

Документация. Разработка Технического описания ПО

и Описания применения ПО"

Москва, МГТУ - 2014

_____________________________________________________________________________________________

СОДЕРЖАНИЕ

1. Цель работы 3

2. Задачи, решаемые в лабораторной работе 3

3. Основные понятия и примеры 4

3.1. Программная документация 4

3.2. Программная документация, разрабатываемая в домашнем задании 4

3.3. Особенности и принципы разработки программной документации (ПД) 5

3.4. Требования к оформлению ПД в ДЗ 5

3.5. Документ описание применения (ОП) ПО и его назначение 6

3.6. Стиль изложения ОП 6

3.7. Разработка ОП 6

3.8. Содержание ОП 6

3.9. Требования к ОП 7

3.10. Документ техническое описание (ТО) ПО и его назначение 7

3.11. Стиль изложения ТО 8

3.12. Содержание ТО 8

3.13. Требования к ТО 8

3.14. Разработка ТО 9

4. Порядок работы и методические указания (основные требования) 9

4.1. Прочитать и усвоить основные понятия данной лабораторной работы. 9

4.2. Разработать документ описание применения ПО (ОП) 10

4.3. Разработать диаграмму классов ПО 10

4.4. Разработать диаграмму классов и систему классов ПО 10

4.5. Разработать документ техническое описание ПО (ТО) 10

4.6. Использование шаблонов и образцов для документов ОП и ТО 10

4.7. Дополнительные требования для сильных студентов 10

5. Варианты по группам и студентам 11

6. Диаграммы классов домашнего задания 14

7. Контрольные вопросы к ЛР 15

8. Сроки и порядок защиты документа ОП и ТО 15

9. Литература 16

10. Приложение: Шаблон документа ОП 16

11. Приложение: Шаблон документа ТО 16

12. Приложение: Образец документа ОП 17

13. Приложение: Образец документа ТО 17

14. Справочные материалы 17

1 Цель работы

Целью лабораторной работы получение навыков разработки документов на программное обеспечение. В работе изучается разработка Технического описания (ТО) и Описания применения (ОП) на программное обеспечение (ПО). Работа выполняется в рамках ДЗ/КЛР. На основе образца и шаблона данных документов, для своего варианта задания, студенты разрабатывают и защищают собственные документы для своего варианта ДЗ. Данная лабораторная работа входит в цикл работ, выполняемых студентами кафедры в рамках практикума по программированию (во 2-м семестре кафедры ИУ5). Кроме этой работы в цикл входят ЛР № 12,14, и 15. Они объединены общей задачей. Порядок работ и требования к ним изложены в документе “ Методические указания для выполнения ДЗ/КЛР по дисциплине Программирование на основе классов и шаблонов кафедры ИУ5”[6], он размещен на сайте дисциплины. Документы оформляются в MS WORD в виде текстовых документов.

2 Задачи, решаемые в лабораторной работе

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

• Прочитать и усвоить основные понятия данной лабораторной работы.

• Прочитать документ требования к ДЗ/КЛР.

• Определить или уточнить у преподавателя номер своего варианта и получить тему ДЗ.

• Познакомиться с требованиями к оформлению документов ЛР.

• Познакомиться с образцами документов ЛР.

• Загрузить шаблон документа и внести необходимые данные для идентификации студента, группы и индивидуального задания студента по вариантам.

• Разработать разделы документов ЛР.

• Прочитать и изучить раздел документа образец: Требования к программной документации.

• Прочитать и изучить раздел документа образец: Стадии и этапы разработки.

• Прочитать и изучить раздел документа образец: Порядок приема и контроля.

• После выполнения перечисленных действий студенты: демонстрируют преподавателю документ, разработанный во время ЛР. Документ оформляется в MS WORD на основе шаблона документа с использованием образца документа.

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

#include <iostream>

2. Вывод результата в консольное окно, который формируется программой, будем помечать коричневым цветом и устанавливать непропорциональный шрифт Courier New. Например:

Введите iVal: 10

3. Формализованные описания языка и синтаксические правила будем записывать зеленым цветом:

<левая часть выражения присваивания> = <правая часть выражения присваивания>;

4. Если в тексте встречается переменная, которая подчеркнута, то это означает, что дается определение важного понятия и это понятие встречается в данном тексте первый раз. Например:

Программа – это упорядоченная совокупность операторов …

3 Основные понятия и примеры

В рамках освоения дисциплины “Программирование на основе классов и шаблонов” студенты выполняют домашнее задание (комплексную лабораторную работу - КЛР) по разработке собственной системы классов. Назначение системы классов определяется вариантом задания. Работы выполняются студентами индивидуально. Работа выполняется частично в часы проведения лабораторных работ – КЛР (комплексная лабораторная работа) по отдельным частям и в часы самостоятельной проработки курса. Результаты работы учитываются во втором модуле курса.

В данной лабораторной работе (части КЛР) изучаются документы: “Описание применения” и “Техническое описание”.

Предварительно повторим общие вопросы разработки программной документации на программное обеспечение (ПО).

4 Программная документация

Любой программный проект должен сопровождаться разработкой комплекса программной документации. Время, которое затрачивается на разработку такой документации соизмеримо со временем самой программной разработки (не менее 50% времени всего проектирования). Иногда это время превышает время программирования и отладки проекта. Некоторые документы разрабатываются до начала разработки. Например, техническое задание (ТЗ) на программную разработку. Без создания грамотного ТЗ проект вообще нереализуем или, скорее всего, не будет успешным. Кроме того, без хорошо разработанного технического задания, невозможно успешно предъявить и сдать работу заказчику, а также, успешно закрыть работу по проекту (включая и получения оплаты за выполненную работу). Программисты (или специальные разработчики документации) разрабатывая документы, по сути, являются “техническими писателями”, а освоение таких умений является неотъемлемой частью получаемых навыков в рамках подготовки по нашей специальности.

5 Программная документация, разрабатываемая в домашнем задании

Для получения основных навыков в разработке технической документации на программное обеспечение выбраны главные документы из значительного множества документов, требуемых в ГОСТ [8]. Этот комплект документов содержит следующие документы:

• Техническое задание (ТЗ);

• Описание применения программного продукта (ОП);

• Техническое описание программного продукта (ТО);

• Руководство пользователя (РП);

• Руководство системного программиста (РСП);

• Исходные тексты программ системы классов и тестового примера (ИТ);

• Программа и методика испытаний на основе тестового примера (ПМИ);

• Описание тестового примера (ОПТ);

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

6 Особенности и принципы разработки программной документации (ПД)

При разработке ПД нужно учесть следующие обстоятельства:

• Кто из участников процесса разрабатывает данный документ ПД.

• Для кого разрабатывается данный документ ПД

• Каков стиль изложения данного документа ПД

• Каково содержание данного документа ПД

• На каком этапе проектирования разрабатывается данный документ ПД

• Каковы требования к данному документу.

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

• Руководители проекта.

• Разработчики программисты (или исполнители проекта).

• Заказчики проекта.

• Пользователи разрабатываемого программного обеспечения (ПО).

• Системные программисты, устанавливающие ПО для пользователя.

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

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

В каждой ЛР из цикла КЛР мы рассмотрим все эти особенности, применительно к каждому типу рассматриваемого документа. Здесь выделим общие особенности стиля изложения и разработки ПД:

• Документы должны содержать информацию, имеющую отношение только к данному проекту и данному документу.

• Документы должны быть написаны на техническом языке и не должны содержать неопределенности и неоднозначности.

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

• Стиль документа должен соответствовать стилю документа данного типа.

• Документы не должны содержать “воды” и отступлений от содержания. Никакой “лирики”.

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

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

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

7 Требования к оформлению ПД в ДЗ

В нашем случае требования к оформлению следующие:

• Текстовый редактор - MS WORD (не Open Office!),

• Шрифт - Times New Roman.

• Кегль шрифта - 12,

• Интервал между строками - одинарный,

• Способы форматирования текста – по ширине,

• Размеры страниц – А4 (верх - 2 , низ - 2 , слева - 3 , справа - 2),

• Содержание колонтитулов (вариант, группа, ФИО студента),

• Способы рисования иллюстраций документа (Предпочтительнее MS Visio можно MS WORD),

• Нумерация страниц – центр – верх.

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

8 Документ описание применения (ОП) ПО и его назначение

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

9 Стиль изложения ОП

Стиль изложения документа “Описание применения” должен быть описательным ("программа имеет возможности …", "программа работает в среде WINDOWS …", "Система позволяет автоматизировать …", "Объекты, создаваемые на основе классов, обеспечивают построение …" и т.д.). Текст в данном документе должен быть написан ясно, без сложных для понимания технических терминов, простым языком. В случае необходимости в нем оформляются наглядные таблицы и диаграммы. Понимание данного материала должно быть доступно не только для специалистов, а и для менеджеров организаций, для которых предлагается использовать программный продукт.

10 Разработка ОП

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

11 Содержание ОП

Содержание документа ОП по пунктам приведено ниже. В образце документа ОП приведено ОП для варианта улиц и домов, описанного в общем пособии по курсу [3]. В шаблоне документа ОП (см. в конце данных методических указаний) даны методические указания к написанию и приспособлению документа шаблона применительно к конкретному варианту студента.