РАЗРАБОТКА ПРОГРАММНОЙ ДОКУМЕНТАЦИИ ПРИКЛАДНОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ

Разработка программный документации является неотъемлемой частью процесса разработки программного обеспечения $($далее ПО$)$f и осуществляется по требованию организации-заказчика. В современных условиях сложилось два основных подхода к ее разработке, обусловленные разными требования стандартов сложившимися на постсоветском пространстве $($СНГ, страны ЕАЭС$)$ и в западных компаниях $($ЕС, Великобритания, США$)$. Компаниям, работающим на международном рынке, в зависимости от требований организации-заказчика регулярно приходится сталкиваться как с одним, так и со вторым подходами.

Виды программных документов и их содержание в странах СНГ и ЕАЭС определяются по ГОСТ 19.101-77 $[1]$. Согласно данному ГОСТ программы подразделяются на компоненты и комплексы, где:

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

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

К программным документам относят:

• Спецификацию;
• Ведомость держателей подлинников;
• Текст программы;
• Описание программы;
• Программу и методику испытаний;
• Техническое задание;
• Пояснительную записку;
• Эксплуатационные документы.

При этом эксплуатационные документы включают в себя:

• Ведомость эксплуатационных документов;
• Формуляр;
• Описание применения;
• Руководство системного программиста;
• Руководство программиста;
• Руководство оператора;
• Описание языка;
• Руководство по техническому обслуживанию.

Кроме видов программных документов ГОСТ определяет стадии проекта на которых они разрабатываются: эскизный, технический и рабочий проекты. При этом согласно ГОСТ обязательными к разработке являются на стадии рабочего проекта:

• спецификация $($для комплекса и для компонента, имеющего самостоятельное применение$)$;
• текст программы $($для компонента$)$.

Необходимость составления остальных документов определяется на этапе разработки и утверждения технического задания.

Спецификация является основным программным документом для комплексов и компонентов, применяемых самостоятельно. Для компонентов, не имеющих спецификации, основным программным документом является «Текст программы».

Спецификация в общем случае содержит разделы:

• документация;
• комплексы;
• компоненты.

Форма спецификации приведена в ГОСТ 19.202-78 $[2]$.

Текст программы – это запись программы с необходимыми комментариями. Требования данной программной документации определены в ГОСТ 19.401-78 $[3]$.

Титульная часть текста программы состоит из листа утверждения и титульного листа составляемых в соответствии с ГОСТ 19.104-78 $($рисунок 1$)$.

Рисунок 1 – Титульная часть «Текста программы»

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

Основная часть документа должна состоять из текстов одного или нескольких разделов, которым даны наименования. Допускается вводить наименование также и для совокупности разделов $($рисунок 2$)$.

Рисунок 2 – Пример содержания «Текста программы»

Кроме указанных частей в тексте программы должна присутствовать часть регистрации изменений. О каждом изменении документа в этой части делается запись в соответствии с требованиями ГОСТ 19.603-78.

Помимо указанных документов наиболее часто требуемыми, согласно техническому заданию, документами являются:

• Описание программы;
• Программа и методика испытаний;
• Руководство программиста

Описание программы содержит сведения о логической структуре и функционировании программы. Описание программы состоит из $($ГОСТ 19.402-78 $[4]$$)$:

• Общих сведений;
• Функционального назначения;
• Описание логической структуры;
• Используемых технических средств;
• Вызова и загрузки;
• Входных данных;
• Выходных данных.

Программа и методика испытаний $($ГОСТ 19.301-79 $[5]$$)$ содержит требования, подлежащие проверке при испытании программы, а также порядок и методы их контроля. Данный документ включает в себя следующие разделы:

• Объект испытаний;
• Цель испытаний;
• Требования к программе;
• Требования к программной документации;
• Средства и порядок испытаний;
• Методы испытаний.

Руководство программиста содержит сведения для эксплуатации программы и должно иметь следующие разделы $($ГОСТ 19.504-79 $[6]$$)$:

• Назначение и условия применения программы;
• Характеристики программы;
• Обращение к программе;
• Входные и выходные данные;
• Сообщения.

Процесс разработки в западных компаниях осуществляется в соответствии с международными стандартами, в частности ISO/IEC/IEEE 90003:2018 структура которого выстроена в соответствии с ISO 9001:2015. При этом компании при разработке руководствуются собственной документацией, составленной с учетом рекомендаций и обязательных требований стандартов. В общем случае документацию по разрабатываемому ПО можно разделить на два типа $[7]$:

• Программная документация;
• Пользовательская документация.

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

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

Программная документация может содержать следующие основные типы документации:

• Документы с требованиями к программе;
• Документы по дизайну UI / UX;
• Документы по проектированию архитектуры ПО;
• Документы содержащие исходный код программы;
• Документация по интерфейсам прикладного программирования $($API$)$;
• Документация по обеспечению качества $($тестированию ПО$)$;
• Документация по техническому обслуживанию или справочное руководство.

Документы с требованиями к программе $($PRD$)$ представляют собой информацию о функциональных возможностях программы, о том, что она должна делать. PRD – это видение и ожидания заказчика в отношении продукта. Как правило, если у заказчика есть специалисты, которые имеют представление о том, как оптимально оформить данные требования, то этим должен заниматься заказчик. Но если подобного опыта нет, то оформление требований может взять на себя разработчик ПО. Этот документ должен быть четким и не допускающим двойного толкования и содержать достаточно информации, чтобы описать цель продукта, его особенности, функциональные возможности, обслуживание и поведение $($бизнес-правила, пользовательские истории, сценарии использования и т.д.$)$

Создание UI / UX - начинается со стадии разработки требований и проходит через все этапы разработки, включая этапы тестирования и релиза. Процесс UI / UX-дизайна включает в себя исследование, создание прототипа, тестирование удобства использования и саму часть проектирования, в ходе которой создается большое количество документации.

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

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

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

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

• Планы управления качеством;
• Документацию для тестирования.

Документация для тестирования может включать в себя:

• Стратегию тестирования;
• План испытаний;
• Документ со спецификациями тестового примера;
• Контрольный список тестов.

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

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

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

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

• Краткое или полное руководство;
• Руководство по устранению неполадок.

Документация системного администратора обычно охватывает установку и обновление ПО, которые помогают системному администратору в обслуживании программного продукта. Стандартными документами системного администратора являются:

• Функциональное описание;
• Руководство системного администратора.

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

Список использованных источников