Чек-лист документации системного аналитика: 13 артефактов, которые должны быть в проекте

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

Проблема начинается, когда документация ведется бессистемно. Часть требований находится в Confluence, решения после встречи остались только в переписке, описание API существует отдельно от бизнес-контекста, а значение важного термина каждый участник проекта понимает по-своему. В результате команда тратит время не на разработку, а на восстановление контекста и повторные уточнения.

При этом универсального правила «в каждом IT-проекте обязательно должны существовать ровно 13 документов» нет. Набор артефактов зависит от продукта, архитектуры, процессов и состава команды. Но есть типовые задачи, с которыми регулярно сталкивается системный аналитик. Для них и собран этот чек-лист аналитика из 13 шаблонов: GUI, GLOS, ALG, BR, GOAL, FR, SWAGGER, MEET, API, PASSPORT, DD, NFR и SPIKE.

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

Документация системного аналитика: четыре основные категории

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

Требования

К этой группе относятся:

BR — бизнес-требования;
FR — функциональные требования;
NFR — нефункциональные требования.

Эти документы отвечают на разные вопросы. BR фиксируют потребность и ожидаемый бизнес-результат. FR описывают функции и поведение системы. NFR определяют характеристики и ограничения: например, требования к производительности, безопасности или надежности. Вместе они описывают цель бизнеса, функцию системы и параметры ее работы.

Проектирование и взаимодействие систем

В эту категорию входят:

GUI — графический интерфейс пользователя;
API — программный интерфейс приложения;
SWAGGER — спецификация API;
ALG — алгоритм.

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

Данные

Здесь находится DD — определение данных.

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

Коммуникации, контекст и управление работой

К этой группе относятся:

MEET — протокол встречи;
GOAL — цели инкремента;
SPIKE — исследовательская задача;
PASSPORT — паспорт приложения;
GLOS — глоссарий.

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

Чек-лист аналитика: 13 основных артефактов

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

1. GUI — графический интерфейс пользователя

GUI (Graphical User Interface) в документации аналитика фиксирует требования и договоренности, связанные с пользовательским интерфейсом и поведением его элементов. В зависимости от проекта здесь могут быть описаны экраны, поля, кнопки, состояния элементов, переходы и реакции системы на действия пользователя.

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

2. GLOS — глоссарий

Глоссарий содержит термины предметной области и их согласованные определения.

На небольшом проекте необходимость GLOS может быть неочевидна. Но по мере роста системы появляются понятия, которые бизнес, аналитики и разработчики могут трактовать по-разному. Например, «клиент», «пользователь» и «плательщик» в конкретной системе могут обозначать разные сущности.

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

3. ALG — алгоритм

ALG описывает последовательность действий, правил или вычислений, по которым система должна получить определенный результат.

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

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

4. BR — бизнес-требования

BR (Business Requirements) фиксируют бизнес-потребность: какую проблему необходимо решить или какого результата хочет добиться организация.

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

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

5. GOAL — цели инкремента

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

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

6. FR — функциональные требования

FR (Functional Requirements) описывают функции и поведение системы — то, что она должна делать.

Например:

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

Хорошее функциональное требование конкретно и проверяемо. FR помогают разработчику понять ожидаемое поведение, а тестировщику — определить, соответствует ли реализованная функция требованиям.

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

«Функциональные требования: как описать, чтобы разработчики не задавали лишних вопросов»

7. SWAGGER — спецификация Swagger/OpenAPI

Здесь важно различать два понятия. API — это интерфейс, через который программные компоненты взаимодействуют друг с другом. OpenAPI Specification — стандарт формального описания HTTP API. Swagger сегодня обозначает экосистему инструментов, работающих с OpenAPI; исторически сама спецификация называлась Swagger Specification.

Такое описание может содержать доступные endpoints, операции, параметры, структуры запросов и ответов, способы аутентификации и другие характеристики API.

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

Поэтому шаблон SWAGGER нужен там, где проект использует соответствующий подход к документированию API и команде необходимо зафиксировать его контракт в структурированном виде.Идентификаторы упрощают обсуждение, трассировку требований и работу с изменениями: вместо «некоего требования про корзину» команда может ссылаться на конкретный FR-02.

8. MEET — протокол встречи

MEET сохраняет результат рабочей встречи: ключевые решения, договоренности, открытые вопросы и следующие действия.

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

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

9. API — программный интерфейс приложения

API (Application Programming Interface) определяет способ взаимодействия программных компонентов.

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

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

10. PASSPORT — паспорт приложения

PASSPORT — это структурированная карточка с ключевой информацией о конкретном приложении или системе.

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

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

11. DD — определение данных

DD (Data Definition) фиксирует структуру и смысл данных, с которыми работает система.

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

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

12. NFR — нефункциональные требования

NFR (Non-Functional Requirements) описывают не сами функции, а характеристики и ограничения системы.

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

Сравним:

FR: система должна позволять пользователю выполнить поиск товара по названию.

NFR: система должна возвращать результаты поиска за установленное время при определенной нагрузке.

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

13. SPIKE — исследовательская задача

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

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

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

Как связаны 13 артефактов аналитика

Эти документы полезно воспринимать не как 13 независимых файлов, а как разные уровни описания одного проекта.

Допустим, компания хочет сократить время обработки заказов.

В BR фиксируется бизнес-потребность. В FR появляются функции, необходимые для ее реализации. NFR задают требования к характеристикам работы системы. GUI описывает существенное для команды поведение интерфейса. ALG раскрывает сложную логику обработки. DD определяет используемые данные.

Если решение предполагает взаимодействие нескольких систем, появляется документация API, а при использовании OpenAPI — соответствующая спецификация. Термины проекта собираются в GLOS, результаты важных обсуждений — в MEET, неизвестный технический вопрос может быть вынесен в SPIKE.

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

Как чек-лист документации помогает в работе

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

Перед началом или на очередном этапе проекта аналитик может пройти по списку и задать себе вопросы:

Понятна ли бизнес-цель изменений?
Зафиксированы ли функциональные и нефункциональные требования?
Достаточно ли описаны интерфейс, алгоритмы и данные?
Есть ли интеграции и задокументированы ли их контракты?
Использует ли команда единую терминологию?
Сохраняются ли решения, принятые на встречах?
Зафиксированы ли результаты исследований и ключевой контекст системы?

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

Чем чек-лист полезен начинающему аналитику и на собеседовании

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

Знание названий само по себе мало что дает. Гораздо важнее уметь объяснить, какую проблему решает документ и когда он действительно нужен.

На собеседовании вместо заученного «аналитик работает с BR, FR и NFR» гораздо содержательнее показать логику:

BR связывают решение с бизнес-задачей;
FR определяют требуемое поведение системы;
NFR задают ее характеристики и ограничения;
DD структурирует описание данных;
API-документация фиксирует интеграционное взаимодействие;
GLOS помогает поддерживать единую терминологию;
MEET сохраняет принятые решения.

Такой подход демонстрирует не знание списка сокращений, а понимание роли документации в разработке.

Где взять шаблоны аналитика для всех 13 документов

… ТУТ: набор готовых шаблонов

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

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

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

В AnalystBox собраны все 13 шаблонов из этого чек-листа: GUI, GLOS, ALG, BR, GOAL, FR, SWAGGER, MEET, API, PASSPORT, DD, NFR и SPIKE. Они выполнены в едином стиле и дополнены пояснениями по заполнению.

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

Главное о документации системного аналитика

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

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

BR, FR и NFR помогают структурировать требования. GUI, ALG, API и спецификации позволяют детализировать решение. DD фиксирует работу с данными. GLOS, MEET, GOAL, SPIKE и PASSPORT помогают сохранить терминологию, договоренности, цели, результаты исследований и контекст. А чек-лист из 13 документов позволяет увидеть всю эту систему целиком и не начинать оформление каждого нового артефакта с нуля.

13 готовых шаблонов вместо 13 пустых документов

Чтобы не тратить время на создание документов с нуля, скачайте готовый набор из 13 шаблонов системного аналитика с пояснениями и примерами.

Забрать набор шаблонов

Как работать с шаблонами

1 шаг Оплатите набор на сайте

2 шаг Скачайте архив с шаблонами

3 шаг Посмотрите структуру, пояснения и примеры

4 шаг Адаптируйте шаблон под задачи своего проекта

13 рабочих шаблонов

GUI · GLOS · ALG · BR · GOAL · FR · Swagger · MEET · API · PASSPORT · DD · NFR · SPIKE

2 бонуса

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

+ Критерии DoR и DoD

Получить весь набор за 2 990 ₽

~~4 990 ₽~~

Выгодная стоимость шаблонов

Получите готовый набор документов со скидкой 40%

Вопросы перед покупкой