шаблон документирования прокта или фичи.md

шаблон документирования.md

Цель

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

Описание

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

Термины и сокращения

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

Полезные ссылки

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

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

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

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

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

Используемые технологии

Опциональный блок, в котором можно перечислить языки программирования (также используемые библиотеки), интеграционную технологию, СУБД.

Сценарии использования (Use case)

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

Компонентная схема

Компонентная диаграмма из нотации UML. Позволяет понять из каких частей состоит система и какие есть взаимодействия на верхнем уровне.

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

Модель данных

## Диаграмма классов или ER-диаграмма.

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

Определите основные сущности и их атрибуты, типы, ограничения и валидации для атрибутов (это часто бывает важно). Определите взаимосвязи между сущностями.

Интеграции

## Внешние

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

## Внутренние

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

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

Для описания задач второго типа предлагается описывать следующие разделы:

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

Описание общего процесс проще всего делать следующим образом:

Общее описание

Раздел, который предполагает обозначение контекста. Что это за функционал, какая цель и ограничения.

Пользовательский сценарий (Use-case)

Описание пользовательских сценариев для общей задачи с перечислением всех альтернатив.

Диаграмма последовательности

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

*source = https://habr.com/ru/post/542128/?utm_source=telegram.me_flows&utm_medium=social&utm_campaign=trebovaniya-ot-sistemnogo-analitika-i-shab *