Архитектура документации 💻

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

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

Вот, например, как может быть устроена документация стильной модной и молодежной микросервисной архитектуры:

🌟описание микросервисов Содержит название, кратко описанное назначение, описание API-методов [спорно - возможно достаточно сваггера] и/или отдельных функций. «Функции» особенно актуальны, если есть функционал, запускаемый по триггеру вычитки сообщений из брокера или каким-нибудь шедулером. В общем, не выведенный в апишку.

🌟описание связей Речь про описание сквозных процессов, затрагивающих несколько микросервисов. Такое удобно аккумулировать в отдельном разделе, связав ссылками с конкретными «функциями» на страницах сервисов. Для наглядности всегда дополняю диаграммами, где-то использую UML-sequence, где-то — знаменитую в узких кругах high level профессионалов нотацию «прямоугольники и стрелки», реже - BPMN. Если в системе есть брокер сообщений, можно сделать сводную страничку по топикам с удобным фильтром-поиском.

🌟контактные лица Если у вас большая команда , сделайте страницу с компетенциями. Кто из разработчиков/аналитиков/тестировщиков разбирается в том или ином сервисе? Соберите знание об этом в табличку, точно пригодится.

➖➖➖➖➖➖➖➖➖➖➖ Всё на месте? Или нужно что-то добавить? Давайте обсудим ⌨️

Ставь ♥️, если пост был полезен