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

1.

Санкт-Петербургский государственный университет телекоммуникаций
им. проф. М.А. Бонч-Бруевича
ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ЦЕНТРОВ
ОБРАБОТКИ ДАННЫХ
Лекция 5. Документирование программного обеспечения
Выборнова Анастасия Игоревна, к.т.н., доцент кафедры ССиПД

2. Документирование ПО

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

3. Документирование ПО

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

4. Документирование ПО

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

5. Документирование ПО

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

6. Внутренняя документация

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

7. Внешняя документация

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

8. Документирование ПО

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

9. Документация по ГОСТ

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

10. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

11. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

12. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

13. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

14. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

15. Документация по ГОСТ 19 (ЕСПД)

ГОСТ 19.101-77 Виды программ и программных
документов:

16. Документация по ГОСТ 19 (ЕСПД)

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

17. Документация по ГОСТ 19 (ЕСПД)

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

18. Документация по ГОСТ 19 (ЕСПД)

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

19. Документация по ГОСТ 34

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

20. Документация по ГОСТ 34

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

21. Документация по ГОСТ 34

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

22. Документация по ГОСТ 34

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

23. Документация по ГОСТ 34

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

24. Документация по ГОСТ 34

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

25. Внешняя документация

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

26. Внешняя документация

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

27. Форматы для создания документации

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

28. Форматы для создания документации

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

29. Форматы для создания документации

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

30. Форматы для создания документации

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

31. Инструменты для создания документации

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

32. Инструменты для создания документации

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

33. Как писать?

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

34. Дополнительно:

Или google:
«Документирование в разработке ПО habrahabr»