Ваши документы! Какая документация помогает работать над IT-проектами

Большинство современных вещей задизайнены так классно, что пользоваться ими можно прямо «из коробки». Инструкция к микроволновке или колонке остаётся ни разу не открытой и отправляется в мусор вместе с пупырчатой плёнкой. То же самое происходит с хорошим мобильным приложением — его просто запускаешь и начинаешь пользоваться.

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

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

Читайте дальше — вас ждёт удивительный экскурс в мир проектной документации, которая обычно предшествует старту разработки 😁

‍

Мы все в IT любим эджайл, и современная разработка действительно не обходится без его элементов. И да — «работающий продукт важнее исчерпывающей документации». Этот принцип эджайл-манифеста подчёркивает, что фокусироваться нужно на создании функционирующего продукта, а не на документировании каждого чиха. Кстати, в текущей версии принципов это звучит иначе и не фокусируется на документации:

«Working software is the primary measure of progress»

Всё. Так или иначе, это не означает, что документация исключена вовсе. Команды, работающие по Agile, стремятся документировать самое необходимое, отдавая приоритет разработке и улучшению продукта.

Стандарты в разработке ПО

В России, как и в других странах, существуют национальные стандарты, которые содержат руководства и рекомендации по документированию процесса разработки ПО:

• ГОСТ Р ИСО/МЭК 12207-2010 определяет общую структуру процессов жизненного цикла программных средств и может служить основой для определения необходимой документации.
• ГОСТ Р ИСО/МЭК ТО 9294-93 предоставляет руководство по управлению документированием программного обеспечения.
• ГОСТ Р 51904-2002 устанавливает общие требования к разработке и документированию ПО встроенных систем.
• ГОСТ Р ИСО/МЭК 15910-2002 описывает процесс создания документации пользователя программного средства.

Ни один из этих стандартов, строго говоря, не «цементирует» использование тех или иных видов документации, а тем более их формат.

Но, например, ГОСТ Р ИСО/МЭК 12207-2010 устанавливает общую структуру процессов жизненного цикла программных средств и включает в себя описание процессов, связанных с разработкой ПО. Хотя стандарт не определяет прямо конкретные виды документации, он описывает процессы, в рамках которых эти документы обычно создаются:

• Процесс анализа системных требований.
• Процесс проектирования архитектуры системы.
• Процесс анализа требований к программным средствам.
• Процесс проектирования архитектуры программных средств.

ГОСТ Р ИСО/МЭК ТО 9294-93 предоставляет руководство по управлению документированием ПО, включая документацию разработки.

С опорой на стандарты и на реальную практику разработки сообщество пришло к использованию нескольких видов документации. Рассмотрим наиболее распространённые:

• ТЗ (техническое задание)
• ЧТЗ (частное техническое задание)
• АР (архитектурное решение)
• ПЗ (пояснительная записка)

Виды проектной документации

ТЗ (техническое задание)

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

ТЗ — это документ, который детально описывает требования и спецификации для выполнения определённого проекта или задачи. Единой универсальной формы ТЗ на разработку цифрового продукта нет. Однако существует несколько релевантных ему подходов и стандартов:

• ГОСТ 34 — российский стандарт, который часто применяется при разработке ТЗ для автоматизированных систем.
• IEEE 29148-2018 — международный стандарт для разработки сложных систем, который предоставляет рекомендации по работе с требованиями, включая их классификацию, анализ, документирование и верификацию.
• Rational Unified Process — спецификация для разработки требований к IT-продуктам.

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

• Общие сведения о проекте, его цели и задачи.
• Требования к функциональности продукта.
• Технические требования.
• Требования к безопасности.
• Этапы работ и контрольные точки.
• Критерии готовности, требования к качеству и тестированию.
• Необходимые ресурсы.

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

ЧТЗ (частное техническое задание)

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

Примером ЧТЗ, дополняющего ТЗ на IT-продукт, может служить задание на любую отдельно взятую фичу. Предположим, компания разрабатывает крупную систему управления складом. Одной из функций этой системы является модуль инвентаризации. Вот как может выглядеть план ЧТЗ для этого модуля 👇

Частное техническое задание: Модуль инвентаризации

1. Общие сведения

1.1 Наименование: Модуль инвентаризации системы управления складом

1.2 Основание: ТЗ на разработку системы управления складом от 01.05.2024

2. Цели и назначение

2.1 Цель: Автоматизация процесса инвентаризации склада

2.2 Назначение: Учет и контроль товарных запасов

3. Требования к функциональности

3.1 Создание плана инвентаризации

3.2 Сканирование товаров с помощью мобильных устройств

3.3 Автоматическое сравнение фактических и учетных данных

3.4 Формирование отчетов о расхождениях

3.5 Интеграция с основной базой данных товаров

4. Технические требования

4.1 Поддержка работы на мобильных устройствах с ОС Android 10 и выше

4.2 Возможность работы в офлайн-режиме с последующей синхронизацией

4.3 Шифрование данных при передаче и хранении

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

5.1 Интуитивно понятный интерфейс для работы на складе

5.2 Поддержка сенсорного ввода

5.3 Возможность голосового ввода данных

ПЗ (Пояснительная записка)

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

• Помогает лучше понять суть проекта и обосновать принятые решения.
• Описывает структуру и компоненты цифрового продукта.
• Содержит общее описание алгоритмов и их схемы.

В IT-проектах пояснительная записка обычно включает следующие разделы:

• Введение.
• Назначение и область применения.
• Технические характеристики.
• Ожидаемые технико-экономические показатели.

ПЗ в IT помогает дать краткий обзор проекта заинтересованным лицам, у которых нет времени вникать во все детали — своего рода питч. В ней есть всё, что нужно рассказать о проекте, пока едете в лифте с тем, от кого зависит финансирование проекта — цели, ценность и способы достижения поставленных задач.

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

АР (Архитектурное Решение)

Архитектурное решение в IT — это документ, описывающий архитектуру программного обеспечения или информационной системы.

Обычно архитектурное решение включает несколько компонентов:

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

АР описывает общую структуру системы, взаимодействие её компонентов, используемые технологии и платформы. Этот документ позволяет оценить масштабируемость, производительность и безопасность будущей системы.

В контексте проектной документации, АР обычно следует за Техническим Заданием (ТЗ) и предшествует более детальной документации по разработке. Оно служит основой для дальнейшего проектирования и разработки системы, обеспечивая связь между бизнес-требованиями и техническими решениями.

Это всё?

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

• Документация разработчиков: UML-диаграммы, code standards.
• Тестовая документация: тест-кейсы, баг-репорты.
• Документация по эксплуатации: гайд по установке и настройке, юзер-справка.