Документирование программного обеспечения презентация

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

Документирование ПО
Тестирование программного обеспечения – это один из этапов его разработки.
Определение требований
Проектирование
Разработка
Тестирование
Поставка
Документация
Сопровождение

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

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

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

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

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

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

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

Документация по ГОСТ 19 (ЕСПД)
ГОСТ 19.101-77 Виды программ и программных документов:

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

Документация по ГОСТ 19 (ЕСПД)
Состав документации зависит от типа программы:
Все остальное – не обязательные документы (о)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как писать?
Для разных документов требуется разный стиль написания.
Для того, чтобы понять, в каком стиле писать, можно найти и прочитать аналогичные документы.
Общие рекомендации для документов, где требуется ясность и простота:
Максим Ильяхов, Людмила Сарычева «Пиши, сокращай» + блог Максима Ильяхова.