Документирование софта и стандарты
10.03.2025
Часть 1: Основы документирования в России
В России документирование программного обеспечения (ПО) раньше строилось на комплексе стандартов ЕСПД (ГОСТ 19). Это типа база, которая задавала правила, как оформлять софт и доки к нему. Потом добавились ГОСТ 34 — стандарты для автоматизированных систем, они более общие, но строгие по структуре жизненного цикла (ЖЦ) и проектным документам. А самые новые — ГОСТ Р ИСО/МЭК, это адаптация международных стандартов ISO/IEC, свежак по времени.
ЕСПД — это старый, но рабочий набор правил для документирования софта.
ГОСТ 19 ЕСПД — это набор правил, как оформлять и вести доки для софта, чтобы все было четко и понятно.
Часть 2: Зачем вообще эти стандарты и какие они бывают?
Зачем нужны
Выбрать модель ЖЦ ПО (как будем его разрабатывать).
Понять, какие доки нужны и что в них писать.
Контролировать качество этих доков.
Решить, в каком формате их делать.
Придумать, как их обозначать, чтобы не запутаться.
Какие бывают
На процесс — как создавать доки.
На сам документ — как он должен выглядеть и что внутри.
На обмен — чтобы все электронные версии были совместимы.
Часть 3: ЕСПД — что это за зверь?
Единая система программной документации (ЕСПД) — это набор ГОСТов, которые регулируют, как разрабатывать, оформлять и хранить софт и доки к нему. Цель — сделать все унифицированным, чтобы:
Программы можно было переиспользовать или обмениваться ими.
Меньше париться с трудозатратами и больше получать профита от разработки и поддержки.
Автоматизировать создание и хранение доков.
На что распространяется
На любой софт для любых компов, систем и задач.
Что внутри ЕСПД
Основные правила (типа фундамента).
Организационные штуки (как все устроить).
Стандарты для форм и содержания доков.
Поддержка автоматизации создания доков.
Часть 4: ЕСПД — где косяки?
ЕСПД — это не идеал, и вот почему:
Заточен только под каскадную модель ЖЦ (сначала одно, потом другое, без гибкости).
Не дает четких советов, как документировать качество софта.
Не дружит с другими стандартами, например, ЕСКД (для конструкторской документации).
Неясно, как документировать софт как товар.
Нет инфы про самодокументирование (типа встроенных подсказок или менюшек в ПО).
Не синхронизирован с международными стандартами.
Короче, ЕСПД немного устарел и не всегда в тренде.
Часть 5: ЕСПД — все еще можно юзать?
Несмотря на косяки, ЕСПД не бесполезен:
Приводит документирование в порядок.
Не такой жесткий, как кажется: можно добавлять свои доки или менять их под заказчика.
Многие заказчики привыкли к нему и любят, как старый добрый свитер.
Как юзать по-умному: берешь нужные стандарты, адаптируешь под проект, добавляешь свои разделы, убираешь лишнее и привязываешь к своей модели ЖЦ. Гибкость наше все!
Часть 6: Структура ЕСПД
ЕСПД делится на группы стандартов:
0 — общие правила.
1 — основы.
2 — как делать доки для разработки.
3 — для изготовления.
4 — для сопровождения.
5 — для эксплуатации.
6 — как хранить и передавать доки.
7-8 — запас (пока пусто).
9 — всякое разное.
Часть 7: Какие бывают доки по ГОСТ 19.101-77?
Есть два типа: программные (для разработки и поддержки) и эксплуатационные (для использования).
Программные доки
Спецификация — что входит в программу и доки.
Ведомость держателей подлинников — где хранятся оригиналы.
Текст программы — код с комментами.
Описание программы — как она работает внутри.
Программа и методика испытаний — как проверять софт.
Техническое задание — для чего софт, требования, сроки.
Пояснительная записка — алгоритмы и решения.
Эксплуатационные доки
Ведомость эксплуатационных доков — список всех доков.
Формуляр — характеристики и инфа об использовании.
Описание применения — для чего софт и как его юзать.
Руководство системного программиста — настройка и поддержка.
Руководство программиста — эксплуатация.
Руководство оператора — как общаться с системой.
Описание языка — синтаксис и семантика.
Руководство по техобслуживанию — для тестов и диагностики.
Часть 8: Конкретные ГОСТы ЕСПД
Вот список ключевых стандартов с их задачами:
ГОСТ 19.201-78 — ТЗ: что писать и как оформлять.
ГОСТ 19.402-78 — описание программы.
ГОСТ 19.404-79 — пояснительная записка.
ГОСТ 19.502-78 — описание применения.
ГОСТ 19.503-79 — руководство для системного прогера.
ГОСТ 19.504-79 — руководство для программиста.
ГОСТ 19.505-79 — руководство для оператора.
ГОСТ 19.508-79 — руководство по техобслуживанию.
ГОСТ 19.301-79 — как тестировать софт.
ЕСПД — это старый, но рабочий набор правил для документирования софта. Не без косяков, но с ним можно жить, если адаптировать под себя. ГОСТы дают структуру, а ты уже сам решаешь, как их крутить под проект. Главное — договориться с заказчиком, и все будет в шоколаде!
Last updated