Документирование и сопровождение ПО. Стандарт по документированию

1.

Документирование ПО
Лекция 14
Тема 5: Документирование и сопровождение ПО
1

2.

Стандарт по документированию
Единая система программной
документации (ЕСПД) – набор
государственных стандартов,
устанавливающих взаимоувязанные
правила разработки, оформления и
обращения программ и программной
документации
4

3.

ЕСПД
установка требований по разработке,
эксплуатации и сопровождению ПО
унификация ПО, позволяющая
обмениваться и производить повторное
использование
снижение трудоемкости и повышение
эффективности разработки, эксплуатации
и сопровождения ПО
автоматизация изготовления и хранения
программной документации
5

4.

Состав ЕСПД
основополагающие и организационно-
методические стандарты (определяют
виды программной документации и
порядок разработки ПО)
стандарты, определяющие форму и
содержание программных документов
стандарты, обеспечивающие
автоматизацию разработки программной
документации
6

5.

Виды программной
документации (ГОСТ 19.101)
Документация управления разработкой
– протоколирование процесса разработки
и обеспечение совместной работы
разработчиков
Эксплуатационная документация –
сведения для обеспечения
функционирования и эксплуатации
программы
9

6.

Д. управления разработкой
Техническое задание – назначение и область
применения программы, технические, техникоэкономические и специальные требования,
предъявляемые к программе и стадии и сроки
разработки, виды испытаний
Спецификация – описание состава программы и
документации на нее
Пояснительная записка – схема алгоритма,
описание функционирования программы,
обоснование принятых технических решений
Текст программы – запись программы с
необходимыми комментариями
10

7.

Эксплуатационная документация
Формуляр (паспорт) – основные
характеристики и комплектность программы и
сведения об эксплуатации программы
Описание применения (справочник
пользователя) – сведения о назначении
программы, области применения, классы
решаемых задач и ограничения, применяемые
методы, требования к техническим средствам и
программному обеспечению
11

8.

Эксплуатационная документация
Руководство системного программиста –
сведения для проверки, установки, настройки
программы (руководство администратора)
Руководство программиста – сведения для
эксплуатации программы и использования ее
компонентов (руководство разработчика,
использующего данную программу как часть
разрабатываемой системы)
Руководство оператора – сведения для
обеспечения процедуры общения оператора с
вычислительной системой (руководство
пользователя)
12

9.

Эксплуатационная документация
Разрабатывается на стадии «Рабочий проект»
Не все документы обязательны для исполнения
Документы могут объединяться
Состав документации определяется на этапе
формулирования требований при составлении
технического задания
19

10.

Общие требования к
программным документам
ГОСТ 19.105
Титульный лист
Информационная часть – содержание и
аннотация документа, предметный
указатель
Основная часть – в зависимости от вида
документа подразделяется на разделы
20

11.

Иностранные стандарты
IEEE 1063-2001 «IEEE Standard for Software User
Documentation»
IEEE 1016-1998 «IEEE Recommended Practice for
Software Design Descriptions»
ISO/IEC FDIS 18019:2004 «Guidelines for the
design and preparation of user documentation for
application software»
ISO/IEC 26514:2008 «Requirements for designers
and developers of user documentation»
21

12.

ГОСТ Р ИСО 9127-94(2003)
«Документация пользователя и информация на
упаковке для потребительских программных
пакетов»
Документация пользователя – документация,
содержащая информацию по установке и
эксплуатации программного продукта
Информация на упаковке – информация о
применимости программного продукта,
требованиях к ресурсам, дающая возможность
принять решение и применимости программного
продукта
22

13.

ГОСТ Р ИСО/МЭК 15910
ГОСТ Р ИСО/МЭК 15910-2002. «Процесс
создания документации пользователя
программного средства».
Поддержка стандарта 12207 (ЖЦ)
Создание документации – процесс на
протяжении всего периода создания ПО
Документатор – разработчик
документации (может совпадать с разработчиком)
Стили оформления документации без
жестких ограничений
23

14.

Показатели качества
ГОСТ Р ИСО/МЭК 12119
Полнота – документация должна
содержать информацию, необходимую и
достаточную для использования
программы:
описаны все функции
описаны граничные значения данных
описаны процедуры установки, настройки,
использования и сопровождения программы
описаны все сообщения выдаваемые
пользователю
25

15.

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

16.

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

17.

Показатели качества
Простота обозрения – простота изучения
документации, оглавление и предметный
указатель
Доступность – определена процедура
получения и распечатки документа не
поставляемого в печатном виде
28

18.

Правила составления Д.
Составление документации на всех этапах
проектирования ПО
Большие и сложные проекты – сохранение
информации
Команда разработчиков – язык
взаимодействия и обмен информацией
Уровень зрелости организации – процесс
сохранения технологии
30

19.

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

20.

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

21.

Правила составления Д.
Поддержание актуальности документации
Отражение в документации процесса
изменения ПО
Своевременное внесение изменений в
документацию !
Несвоевременность – причина неполноты и
некачественной документации
Внесение изменений во всю
документацию
Отсутствие противоречий
33

22.

Правила составления Д.
Единый стиль и язык, система
определений и понятий в документации
Средство хранения информации и
взаимодействия
Использование стандартов
Как оформлять
Что документировать
Простота и структурность
Разбиение на части
Оглавление
Предметные указатели
34

23.

Способы использования Д.
Быстрый старт – поиск в документации сведений
об установке, настройке, запуске и выполнении
программы
Ознакомительное чтение – освоение продукта в
целом и решение типовых задач
Методическое освоение – детальное изучение
программы и всех ее возможностей
Целевой поиск – поиск путей решения конкретной
задачи или выполнения конкретного действия
Целевой запрос – запрос справочной информации
по конкретной функции или элементу управления
пользовательского интерфейса
35

24.

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

25.

Системы автоматизации Д.
Создание в автоматическом режиме части
документации ПО на основе анализа
исходных текстов программы
Кроссплатформенные системы
Поддержка большого количества языков
программирования (C, Python, Java, PHP,
VHDL…)
Поддержка большого количества выходных
форматов документации (HTML, XML, RTF,
PDF, man, CHM…)
Генерация красивой и удобной документации
37

26.

Автоматизация DOC
Входные данные
Построение документации на основе специальных
комментариев и директив в исходных кодах
Построение документации на основе структуры
программы (модули, функции, их взаимосвязь)
Включение дополнительной информации
(«о программе», рисунки, схемы, формулы)
Выходные данные
Интерактивная документация в электронной форме
(поиск, внутренние и внешние ссылки на
документацию)
Диаграммы компонентов, диаграммы классов,
диаграммы последовательности и т.п.
38

27.

Автоматизация DOC
Документирование файлов проекта
Документирование функций и методов (входные
и выходные данные и т.п.)
Документирование классов
Документирование исключений
Документирование перечислений
Создание групп и подгрупп элементов для
логической структуризации проекта
39

28.

Достоинства
Легкость поддержания актуальности
документации, изменение в одном месте
изменения в исходных текстах
запуск системы документирования
= обновленная документация
Не требует дополнительных затрат для
грамотно написанного исходного кода
(комментарии в нужном формате)
Единый стиль оформления по стандартам
и требованиям, на основе шаблонов
40

29.

Примеры
DOXYGEN
qDOC
Pydoc
Docstring
41

30.

DOXYGEN
Консольное приложение
Работа аналогично компилятору – генерация
документации на основании анализа
исходных кодов
Конфигурация проекта, для которого
создается документация, хранится в
текстовом файле конфигурации
Наличие утилит с графическим интерфейсом
Кроссплатформенность (Linux, Mac OS X,
Solaris, Microsoft Windows)
42

31.

Документирующие блоки
// Однострочный блок – краткое описание
элемента, заголовок
/**/ Многострочный блок – подробное
описание элемента
Использование в блоке дополнительных
ключей для указания автора, версии, даты
разработки и т.п.
///< Документирующий блок размещен после
элемента
int variable; ///< Краткое описание
43

32.

Документирующие блоки
/*!
\brief Родительский класс, не несущий никакой см
ысловой нагрузки
Данный класс является примером для того, как док
ументируется наследование
*/
class Parent {
public:
Parent();
~Parent();
};
44

33.

Документирующие блоки
/*!
\brief Дочерний класс
\author Norserium
\version 1.0
\date Март 2015 года
\warning Данный класс создан
только в учебных целях
Обычный дочерний класс,
который унаследован от
ранее созданного класса
Parent */
class Son : public Parent {
public:
Son();
~Son();
};
45

34.

Документирование ПО
Лекция 14
Тема 5: Документирование и сопровождение ПО
46

35.

Вопросы
1.
2.
3.
Документирование ПО. ЕСПД. Виды
программной документации.
Документация ПО. Показатели качества.
Правила составления. Способы
использования.
Системы автоматизации документирования
ПО. Назначение. Пример.
47