Документировать АС по ГОСТу 34

1) Начнем с изучения задачи

После того, как получили задачу на документирование АС, необходим обзор по всей системе и внешним связям. Архитектор или ведущий аналитик рассказывают про систему в целом, про ее компоненты, подсистемы, внешние связи с другими системами, ключевых специалистов со стороны заказчика. В ТЗ в разделе «Требования к документированию» изучаем комплект документов, который требуется написать.

2) Изучим ПО системы

После встречи с архитектором пора анализировать систему. Необходимо изучить основные компоненты системы: ПО (общее и специальное), СУБД, экземпляры БД. Определения ПО возьмем из ГОСТ 34.003-90 «Автоматизированные системы. Термины и определения»:

Специальное программное обеспечение автоматизированной системы (СПО) — часть программного обеспечения АС, представляющая собой совокупность программ, разработанных при создании данной АС.

процесс документирования

Этапы документирования

Общее программное обеспечение автоматизированной системы (ОПО) — часть программного обеспечения АС, представляющая собой совокупность программных средств, разработанных вне связи с созданием данной АС. Примечание: Обычно ОПО АС представляет собой совокупность программ общего назначения, предназначенных для организации вычислительного процесса и решения часто встречающихся задач обработки информации.


В результате изучения ПО АС составим такую таблицу, в которой будут указаны технические данные по каждому компоненту системы. В таблице могут быть такие колонки: Имя сервера, Функциональное назначение, ОС, ОПО, СПО (Название сервиса, Обозначение сервиса, Краткая характеристика сервиса). Возможно имеет смысл отправить эту таблицу архитектору и разработчикам в качестве опросника. Каждый заполнит свою часть. Лучше всего сделать эту таблицу с публичным доступом в google-таблицах.

Изучим технические связи между ОПО, СПО, СУБД и логические связи между экземплярами БД. Информацию запросим у архитектора и разработчиков. В изучении АС поможет существующая документация: предпроектная (концепция системы), проектная (ТЗ и функциональные требования), конкурсная (КД). Также изучим всю информацию в базе знаний (XWiki, Confluence). Некоторые данные могут быть в задачах Jira, в том числе в комментариях к задачам.

3) Напишем документы стадии ТП (технический проект)

Разработку документации разделим на несколько итераций. В первой итерации опишем основные компоненты системы, а в последующих итерациях — служебные компоненты. Это позволит сократить время на создание черновых версий документов. Первый и главный документ, который надо написать — это П2. В пояснительной записке приводится максимум тех. информации: решения по структуре системы, состав функций, решения по КТС, решения по составу информации, решения по составу программных средств и т.д. (смотрим стандарты КСАС и ЕСПД; после отмены ГОСТа РД 50-34.698-90 разработчику документа рекомендуется самостоятельно определять содержание документа в зависимости от объекта проектирования: системы, подсистемы).

Шаблоны документов стадий ТП и РД:


В качестве исходных данных возьмем информацию, собранную на предыдущих шагах. Все схемы согласовывать с командой. Информацию запрашиваем у архитектора, аналитика и разработчиков.

После П2 пишем следующие документы, которые входят в стандартный комплект документации по ГОСТу 34: ПА, ПВ, П9, П5, ПД. В этих документах подробно расписывается информация, приведённая в документе П2. Информация в некоторых подразделах может дублироваться.

Каждому документу присваивается собственное обозначение: децимальный номер. Пример такого номера: ННН.8952201.555.ПА.01 (документ «Описание программного обеспечения»). Эти номера запрашиваем у администратора проекта. Требования к формату этих номеров смотрим в ГОСТе 34.201-89 «Виды, комплектность и обозначения документов при создании автоматизированных систем».

4) Напишем документы стадии РД (рабочая документация)

а) ПМИ

Чтобы написать ПМИ, на некоторое время нужно стать тестировщиком и пройти все бизнес-сценарии, а затем описать кейсы, позволяющие полноценно проверить функциональность системы. Тестировщик поможет с тестовыми данными и настройками АРМ, расскажет про особенности работы той или иной функции. Подробность и формат описания тест-кейсов зависит от требований заказчика. По умолчанию достаточно описания предварительных условий, последовательности шагов для проверки разработанных функций системы и ожидаемого результата. Иногда требуется написать помимо основных сценариев еще и альтернативные (негативные) сценарии: выполнение операций в системе, нарушающих установленный бизнес-процесс. Но на проектах по ГОСТу, скорее всего, это не пригодится.

б) Руководства

При разработке руководства администратора и руководства по инсталляции изучаем настройки в конфигурационных файлах (*.properties, *.config, *.json) и команды, необходимые для инсталляции системы и управления ее компонентами (например: запуск, перезагрузка, останов, просмотр статуса сервиса). Системный администратор должен проконсультировать по тому, как устанавливаются и настраиваются компоненты системы. Также для написания руководства администратора изучаем и описываем настройки, которые доступны в веб-интерфейсе установленной системы – функции административной панели. Если нет доступа к консоли сервера и административной панели или доступ затруднен, то системный администратор должен предоставить необходимые данные для документов: системные команды, скрины настроек, данные для ввода.

При разработке руководств пользователей изучаем систему с точки зрения конечного пользователя. Описываем подробно каждую функцию, выполняемую с использованием веб-интерфейса системы. Особенности работы функций изучаем в ТЗ/ЧТЗ или выясняем у бизнес-аналитика. Писать руководство лучше всего по стенду, который предназначен для демонстраций заказчику, т.к. на этом стенде развернута актуальная версия системы и введены корректные данные. Рисунки должны быть с данными, приближенными к «боевым», а не с названиями записей «тестУшОлнаобед». По рисункам пользователю должно быть понятно, какие данные вводить в систему при выполнении той или иной операции.

По возможности следует посещать внешние демонстрации системы. Это позволит быть в курсе доработок, которые поступают от заказчика в виде замечаний/пожеланий и которые следует отразить в руководствах и остальных документах стадий РД и ТП. Если присутствие невозможно на внешних демонстрациях, то следует ознакомиться с протоколом встречи.

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

5) Оформим ОРД (организационно-распорядительные документы)

Шаблоны актов и протоколов лучше подготовить до проведения предварительных испытаний, опытной эксплуатации и приемочных испытаний. При сжатых сроках сдачи проекта может не быть времени на их оформление.

6) Обновим написанное

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

Главное

На каждой стадии создания АС необходимо зафиксировать технические данные, которые нужны для написания конкретного документа, путем опроса ответственных специалистов, изучения информации в базе знаний или посредством тестирования системы. Вся команда разработки должна оперативно предоставлять полную техническую информацию о новых доработках в системе — только тогда документация будет полной и актуальной. В итоге заказчик должен получить документацию, которую сможет применить для обслуживания и полноценной эксплуатации системы.