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

Делал для одной компании. Не универсально.

Введение

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

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

Трехбуквенные аббревиатуры

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

PV – Product Vision – продуктовое видение

PRD – Product Requirements Document

PSD – Product Specification Document

UI/UX Guide – User Interface/ User eXperience Guide

SRD – Software Requirements Document

SRS – Software Requirements Specification

TDD – Technical Design Document

FSD – Functional Specifications Document

TSD – Technical Specifications Document

SAM – System Administration Manual

UM – User Manual

Применяемые документы

Для платформы в целом

Наименование	ТБА	Назначение	Ответственный	Получатель (пользователь)
Концепция платформы	PV	Определение целей и задач продукта.	Владелец платформы	Все сотрудники ЦТП
Функциональная структура (ФС)	PRD, PSD	Определение реестра сервисов, функциональной архитектуры, потоков данных между сервисами и с другими системами, базовой ролевой и функционально-ролевой моделью в терминах прикладной области без учета технического контекста	Функциональный архитектор ЦТП	Владелец сервиса ЦТП, Функциональный архитектор ЦТП
Требования к интерфейсу	UI/UX Guide	Определение единых требований к интерфейсу, визуальным элементам	Дизайнер платформы	Разработчик
Технические требования к сервису	SRD	Определение единых технических требований к разрабатываемому сервису в целях подключения в единую платформу и обеспечения совместимости.	Системный архитектор	Разработчик

Для каждого сервиса в отдельности

Наименование	ТБА	Назначение	Ответственный	Получатель (пользователь)
Концепция сервиса (КС)	PV, BRD	Определение целей и задач сервиса, основных пользователей, места в экосистеме.	Владелец продукта (сервиса) ЦТП	Бизнес-аналитик ЦТП
Функциональные требования (ФТ)	PRD, PSD	Определение реестра функций, требований к ним, ролевой и функционально-ролевой модели в терминах прикладной области без учета технического контекста	Бизнес-аналитик ЦТП	Системный аналитик ЦТП
Техническое задание (ТЗ)	SRD, SRS	Определение требований к информационной системе исходя из функциональных требований, с учетом технических аспектов и с учетом технического  контекста	Системный аналитик ЦТП	Разработчик
Частное техническое задание (ЧТЗ)	STS	Определение детальных требований к технической реализации программного продукта	Разработчик (функциональный архитектор)	Разработчик (системный архитектор)
Технический проект	TDD	Определение проектных решений и заданий на разработку	Разработчик (системный архитектор)	Разработчик (программист)
Функциональная спецификация	FSD	Описание функциональных модулей программного обеспечения, функциональное описание структуры данных	Разработчик (функциональный архитектор)	Архитектор ЦТП
Техническая спецификация	TSD	Описание структуры базы данных, спецификация на API	Разработчик (системный архитектор)	Архитектор ЦТП
Программа и методика испытаний (ПМИ)		Требования, подлежащие проверке при испытании программы, а также порядок и методы их контроля.
Руководство системного администратора	SAM	Описание процедур установки и обеспечения  эксплуатации программного обеспечения	Разработчик	DevOps ЦТП
Руководство функционального администратора		Описание процедур функциональной настройки программного обеспечения	Разработчик (функциональный архитектор)	Функциональный администратор ЦТП
Руководство пользователя	UM	Описание функциональности и процедур для пользователей системы	Разработчик (технический писатель)	Пользователь
Паспорт ПО		Информация о системе, необходимая для обеспечения её эксплуатации.	Разработчик (DevOps)	DеvOps ЦТП

Описание документации

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

Концепция платформы

Документ создается для формирования единой системы ценностей и целеполагания при формировании сервисов платформы и её развития в целом.

Концепция определяет:

• Цели создания и существования платформы.
• Задачи, выполняемые платформой для реализации целей.
• Стороны, вовлеченные в использование платформы.

Функциональная структура

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

В документе фиксируется текущая информация о:

• Реестре сервисов.
• Функциональной архитектуре платформы, как совокупности сервисов, объединенной потоками данных.
• Потоках данных с внешними по отношению к платформе системами.
• Базовой функциональности, относящейся ко всей платформе.
• Базовых ролевой и функционально ролевой модели.

Требования к интерфейсу

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

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

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

Концепция сервиса

Концепция сервиса разрабатывается для определения основных характеристик и направления развития нового сервиса. Разработка концепции продукта помогает предпринимателям и командам разработчиков:

1. Понять, какой продукт или услуга нужны рынку и потребителям.
2. Сфокусироваться на основных характеристиках и преимуществах продукта.
3. Принять обоснованные решения о разработке, производстве и маркетинге продукта.
4. Снизить риски и сократить время на разработку и запуск продукта.
5. Обеспечить согласованность между различными участниками проекта (инвесторами, разработчиками, маркетологами).

В документе указываются:

• Цели создания сервиса с указанием их влияния на основную цель платформы.
• Задачи, выполняемые сервисом.
• Проблемы, решаемые сервисом (при наличии).
• Аудитория сервиса.
• Место в экосистеме сервиса, влияние и взаимодействие с другими сервисами платформы или иными внешними системами.
• Качественные и количественные показатели сервиса (плановое количество компаний, воспользовавшихся сервисом, ожидаемый эффект от реализации для отдельной компании, для всех компаний, воспользовавшихся сервисом и т.п.).
• Описание сервиса в бизнес-терминах, логика, безотносительно к применению программного продукта и информационных технологий вообще.

Функциональные требования

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

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

Техническое задание

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

В документе указываются:

1. Введение: содержит общую информацию о проекте, заказчике и исполнителе.
2. Описание продукта: определяет цели и задачи проекта, основные функции и характеристики продукта.
3. Требования к продукту: включает функциональные, нефункциональные и интерфейсные требования к продукту.
4. Проектирование и разработка: описывает процесс разработки продукта, используемые технологии и стандарты.
5. Тестирование и отладка: устанавливает критерии качества продукта, описывает процедуры тестирования и отладки.
6. Внедрение и поддержка: определяет порядок внедрения продукта, планы обучения пользователей, процедуры обновления и технической поддержки.
7. Контроль и отчетность: устанавливает порядок контроля выполнения работ, требования к документации и отчетности.
8. Приложения: могут включать примеры требований, шаблоны документов, справочные материалы и другую дополнительную информацию.

Частное техническое задание

Частное техническое задание детализирует общие требования и подходы, определенные в общем техническом задании.

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

Структура частного технического задания аналогично структуре основного технического задания.

Технический проект

Технический проект – это комплекс документов, разрабатываемых в процессе проектирования программного обеспечения определяющий все аспекты архитектуры программного обеспечения, описания необходимых разработок/доработок, план выполнения задач по разработке.

Состав определяется разработчиком.

Является внутренним документом разработчика и может не предоставляться ЦТП.

Функциональная спецификация

Функциональная спецификация описывает функциональную структуру и потоки данных сервиса в окончательном состоянии после завершения разработки в бизнес-терминах безотносительно примененной платформы.

Документ необходим для :

• функциональных архитекторов в целях наличия исходной информации при планировании развития сервисов;
• технических писателей в целях формирования пользовательской документации.

В документе указываются:

1. Описание автоматизируемых процессов в формате IDEF0 или аналогичной (строго следование нотации не требуется).
2. Функциональную архитектуру диаграмму системы в формате IDEF0 или аналогичном (строгое следование нотации не требуется).
3. Диаграмму потоков в формате DFD или аналогичном (должны присутствовать функциональные модули системы, внешние по отношению к системе источники и получатели данных, передаваемые или получаемые данные). Формируется, если потоки не отображены на функциональной диаграмме.
4. Общее описание системы в бизнес-терминах (как в концепции и функциональных требованиях, но с учетом фактической реализации).

Техническая спецификация

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

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

В документе указываются:

• Описание задействованных технологий и инструментов.
• Архитектура компонентов.
• Структура базы данных.
• API.

Программа и методика испытаний

Программа и методика испытаний (ПМИ) — это документ, который описывает процесс тестирования программного обеспечения или системы.

В документе указываются:

• план испытаний;
• методы тестирования;
• критерии приемки;
• прочие важные аспекты тестирования.

Руководство системного администратора

Руководство системного администратора сервиса (System Administrator Manual) — это документ, предназначенный для системных администраторов, который содержит информацию о том, как устанавливать и настраивать сервис. Руководство может включать в себя информацию о настройке оборудования, установке и обновлении программного обеспечения, управлении пользователями и группами, обеспечении безопасности и решении возникающих проблем.

Структура документа не регулируется.

Руководство функционального администратора

Руководство функционального администратора сервиса (Functional Administrator Manual) содержит информацию о том, как производить настройку функциональности или нормативно-справочной информации сервиса, если сервис предусматривает возможность такой настройки без привлечения разработчиков.

Структура документа не регулируется.

Руководство пользователя

Руководство пользователя (User Guide) — это документ, который помогает пользователю ознакомиться с продуктом и научиться использовать его функции. Руководство содержит информацию работ c функциями сервиса, а также решении возможных проблем.

Структура документа не регулируется.

Паспорт сервиса

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

Паспорт состоит из следующих разделов:

1. Общая информация об информационной системе:
   1. состав подсистем и информация о них
   2. используемые программные продукты и ПО
   3. используемое оборудование (собственное и арендуемое);
   4. стоимость внедрения (в том числе по подсистемам);
   5. стоимость сопровождения (на год).
2. Состав информационной системы:
   1. основные компоненты и подсистемы;
   2. вспомогательные компоненты и поддерживающие системы, которые предоставляют необходимые ресурсы и вычислительные мощности, а также обеспечивают мониторинг, управляют выполнением регламентных работ и контролируют оперативное реагирование на нештатные ситуации;
   3. средства защиты информации.
3. Основные эксплуатационные характеристики информационной системы:
   1. контролируемые параметры;
   2. документация;
   3. политика управления учетными записями пользователей;
   4. регламент резервного копирования и восстановления;
   5. нестандартные процедуры, мониторинг и регламентные работы;
   6. взаимодействие с поставщиком (техническая поддержка).
4. Порядок изменения паспорта информационной системы и контроль его актуальности.