Документирование программного обеспечения. Внешняя и внутренняя документация

1.

14.03.2023
Документирование программного
обеспечения.
Внешняя и внутренняя
документация

2.

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

3.

Документирование ПО
Кто пишет документацию?
■ Системный аналитик – техническое задание и другие
документы, фиксирующие требования к ПО.
■ Тестировщик или QA-аналитик – документация,
связанная с тестированием (тест-план, test cases и др).
■ Технический писатель – техническое задание,
руководства пользователя, администратора, другая
пользовательская документация.
■ Product manager – пользовательские материалы.
■ Копирайтер – пользовательские материалы.

4.

Программная документация
ВНЕШНЯЯ –
всевозможные
руководства для
пользователей,
техническое задание,
справочники
ВНУТРЕННЯЯ –
внутренние стандарты,
комментарии исходного
текста, технологии
программирования

5.

Документирование ПО
Всю документацию можно разделить на два вида:
■ внутреннюю документацию, которая используется в
процессе разработки ПО и недоступна
пользователю;
■ внешнюю документацию, которая создается для
заказчика или пользователя

6.

Внутренняя документация
Внутренняя документация создается всеми членами
команды и призвана облегчить коммуникацию и передачу
опыта, сделать процесс разработки ПО более понятным и
прозрачным.
■ Use cases и другие аналитические документы,
создаваемые в процессе проектирования ПО.
■ Тест-план, test cases.
■ Руководства по развертыванию приложений (deploy).
■ Внутренняя база знаний.
■ Описание принятых в компании процессов разработки и
др.

7.

Внешняя документация
Внешняя документация создается обычно аналитикам
и техническими писателями с целью облегчения
коммуникации с заказчиком/пользователем на всех
стадиях разработки ПО.
■ Техническое задание.
■ Протокол приемо-сдаточных испытаний (ПСИ).
■ Руководство администратора, руководство
пользователя.
■ И др.

8.

Документирование ПО
Как еще можно классифицировать документацию?
■ Проектная
■ Техническая
■ Пользовательская
■ Маркетинговая

9.

Документация по ГОСТ
При создании документации «по ГОСТ» важно выбрать
правильный ГОСТ. При создании программных
продуктов чаще всего речь будет идти об одном из
следующих «зонтичных» стандартов:
■ ГОСТ 19 – Единая система программной
документации (ЕСПД).
■ ГОСТ 34 – Автоматизированные системы.

10.

Документация по ГОСТ 19
(ЕСПД)
Состав документации зависит от типа программы:
■ Компонент – программа, рассматриваемая как
единое целое, выполняющая законченную функцию
и применяемая самостоятельно или в составе
комплекса.
■ Комплекс – программа, состоящая из двух или более
компонентов и (или) комплексов, выполняющих
взаимосвязанные функции, и применяемая
самостоятельно или в составе другого комплекса.

11.

Документация по ГОСТ 19
(ЕСПД)
ГОСТ 19.101-77 Виды программ и программных
документов.
Разные документы разрабатываются на разных стадиях
проектирования, таких как:
Эскизный проект.
Технический проект.
Рабочий проект (основная часть эксплуатационных
документов).

12.

Документация по ГОСТ 34
ГОСТ 34.201-89 Виды, комплектность и обозначение
документов при создании автоматизированных систем.
На стадии эскизного проекта:
■ Ведомость эскизного проекта
■ Пояснительная записка к эскизному проекту

13.

Документация по ГОСТ 34
На стадии эскизного или технического проекта:
■ Схема организационной структуры
■ Схема структурная комплекса технических средств
■ Схема функциональной структуры
■ Перечень заданий на разработку специализированных
(новых) технических средств
■ Схема автоматизации
■ Технические задания на разработку специализированных
(новых) технических средств

14.

Документация по ГОСТ 34
На стадии технического проекта:
■ Задания на разработку строительных, электротехнических,
санитарно-технических и других разделов проекта,
связанных с созданием системы
■ Ведомость технического проекта
■ Ведомость покупных изделий
■ Перечень входных сигналов и данных
■ Перечень выходных сигналов (документов)
■ Перечень заданий на разработку строительных,
электротехнических, санитарно-технических и других
разделов проекта, связанных с созданием системы
■ Пояснительная записка к техническому проекту

15.

Документация по ГОСТ 34
На стадии технического проекта:
■
■
■
■
■
■
■
■
■
■
Описание автоматизируемых функций
Описание постановки задач (комплекса задач)
Описание информационного обеспечения системы
Описание организации информационной базы
Описание систем классификации и кодирования
Описание массива информации
Описание комплекса технических средств
Описание программного обеспечения
Описание алгоритма (проектной процедуры)
Описание организационной структуры

16.

Внешняя документация
Какая еще внешняя документация может быть?
■ White paper – описание продукта, позволяющее
потенциальному клиенту принять взвешенное решение о
его приобретении.
■ Best practice – описание успешного опыта внедрения
использования продукта какой-либо компанией.
■ Описание продукта в магазинах приложений (App
Store, Google Play и др.)
■ Release notes – описание изменений, внесенных в новой
версии ПО.

17.

Внешняя документация
Какая еще внешняя документация может быть?
■ Frequently asked questions (FAQ) – примеры
вопросов, которые часто задают клиенты, и ответы
на них.
■ Справки (help) в нативных приложениях.
■ Различные учебные статьи и описания
использования продукта.
■ Статьи в блогах.
■ Тексты в пользовательских интерфейсах.

18.

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

19.

Форматы для создания
документации
Справочная документация для нативных приложений
может создаваться в форматах справок:
■ chm (ОС семейства Windows).
■ man (Linux-системы).

20.

Форматы для создания
документации
Для web-приложений более удобным выбором будет
использование следующих форматов:
■ HTML – язык гипертекстовой разметки.
■ Wiki-разметка – более просто, чем HTML, очень
популярна, но нет единого стандарта.

21.

Форматы для создания
документации
Другие варианты форматов для программной и
справочной документации:
■ Markdown – еще один упрощенный по сравнению с
HTML тип разметки.
■ LaTeX – система верстки, очень популярная в
академической среде, в том числе из-за широких
возможностей по записи формул.

22.

Инструменты для создания
документации
Существует большое количество инструментов для
создания и поддержки документации:
■ HTML help workshop – для создания chm справок
для приложений Windows.
■ Пропиетарные приложения для создания руководств
и справочников, например, Help and manual.
■ Блокнот + Git
■ Проект MediaWiki – широко распространненное ПО
для wiki-проектов.

23.

Инструменты для создания
документации
Существует большое количество инструментов для
создания и поддержки документации:
■ Модули базы знаний различных Service desk систем
(поддержка пользователей неразрывно связана с их
образованием путем чтения базы знаний).
■ Confluence (Atlassian), для совместного
использования с Jira.
■ Google Drive и другие облачные сервисы.
■ Evernote.