Структурируем документацию проекта. Часть 3
5. Бэк документация
В этом разделе описываем, как работает система. Как обрабатываются запросы пользователей, как осуществляется взаимодействие внутренних компонентов и внешних систем и т.д.
5.1. Описание метода API
Описывать методы API можно несколькими способами - с помощью Swagger или вручную, но главное, чтобы методы были описаны. Это позволит минимизировать ошибки при разработке с последующим поддержанием работоспособности системы. О постановке на разработку API можно почитать тут.
Пример запроса:
https://{baseurl}/parent/56568989
Пример тела ответа:
5.2. Описание топика Kafka
Если есть интеграции с помощью Kafka, то необходимо задокументировать структуру сообщений. Вот как это можно сделать.
Примеры сообщений:
5.3. Технические алгоритмы/функции
В этом разделе содержатся сценарии и алгоритмы работы системы, сценарии взаимодействия внутренних и внешних компонентов. К основным алгоритмам приводите альтернативные сценарии работы системы. Чтобы наглядно отобразить работу системы используйте диаграммы последовательности. Для удобства и поддержания единой картины настраивайте связи между алгоритмами, описаниями методов и сообщений.
Диаграмма последовательности для технического алгоритма
6. Продуктовая аналитика
Раздел, содержащий события и метрики для последующего анализа взаимодействия пользователей с цифровым продуктом.
6.1. События
Описание опорных точек, классифицирующих пользователя.
6.2. Метрики
Карта метрик, чтобы понимать, что и как можно посчитать. Метрики для удобства можно вести по категориям: технические, продуктовые.
6.3. Логирование
Описание запланированных к сохранению логов для последующего разборов инцидентов.
Если вы хотите получить шаблон в pdf формате, то переходите по ссылке в телеграмм-канал.