18

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

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

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

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

Эксплуатационная документация. Разработка документов Руководство пользователя и Руководство системного программиста"

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

_____________________________________________________________________________________________

СОДЕРЖАНИЕ

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

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

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

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

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

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

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

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

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

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

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

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

3.10. Документ руководство системного программиста (РСП) ПО и его назначение 7

3.11. Стиль изложения РСП 7

3.12. Содержание РСП 7

3.13. Требования к РСП 8

3.14. Разработка РСП 9

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

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

4.2. Разработать документ руководство пользователя РП. 9

4.3. Разработать документ руководство системного программиста РСП. 10

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

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

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

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

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

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

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

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

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

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

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

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

1 Цель работы

Целью лабораторной работы получение навыков разработки документов на программное обеспечение. В работе изучается разработка Руководство пользователя (РП) и Руководство системного программиста (РСП) на программное обеспечение (ПО). Работа выполняется в рамках ДЗ/КЛР. На основе образца и шаблона данных документов, для своего варианта задания, студенты разрабатывают и защищают собственные документы для своего варианта ДЗ. Данная лабораторная работа входит в цикл работ, выполняемых студентами кафедры в рамках практикума по программированию (во 2-м семестре кафедры ИУ5). Кроме этой работы в цикл входят ЛР № 12,13, и 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 Стиль изложения РП

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

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

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

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

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

Содержание документа РП:

1. НАЗНАЧЕНИЕ И УСЛОВИЯ ПРИМЕНЕНИЯ СИСТЕМЫ КЛАССОВ

2. ПОДКЛЮЧЕНИЕ СИСТЕМЫ КЛАССОВ И ДИАГРАММА КЛАССОВ

3. РАБОТА С СИСТЕМОЙ КЛАССОВ

4. КЛАСС ХХХ

4.1 Использование свойств ХХХ класса ХХХ с примером…

4.2 Использование метода ХХХ класса ХХХ с примером…

5. ОТКЛЮЧЕНИЕ СИСТЕМЫ КЛАССОВ

6. ОПИСАНИЕ СООБЩЕНИЙ ОБ ОШИБКАХ И ИСКЛЮЧИТЕЛЬНЫХ СИТУАЦИЙ ПРИ РАБОТЕ С ПРОГРАММОЙ

12 Требования к РП

Главные требования к основным разделам документа “Руководства пользователя” (на выполнение этих требований будет обращаться повышенное внимание при сдаче ПО) рассмотрены ниже: