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

Считаю еще одним обязательным пунктом, что должно присутствовать в БЗ - это описание инфопотоков. Это может быть список с минимальным описанием, но обязательно содержащий все интеграции. Или может быть развернутое описание протоколов взаимодействия с запросами и ответами. Это описание всегда только ускоряет команду. Ускоряет адаптацию новичков, опытным помогает быстрее проектировать изменения или находить ошибки, улучшает взаимодействие с другими командами. Не нужно тратить полдня чтобы просто разобраться, что и куда идет. При выводе изменений на production вы не сломаете соседний сервис, потому что не знали про него. При расследовании инцидента вы легко найдете куда она ведет. Опытный сотрудник не уносит знания в своей голове при увольнении.

«Не нужно писать романы», достаточно для каждой интеграции описать направление и тип связи - синхронный/асинхронный, API или Kafka, и т.д. Тут же следует описать контракт взаимодействия: набор сообщений с составом полей. Было бы идеально добавить простейшую компонентную диаграмму (это не sequence и много времени не отнимет).

В дальнейшем поддержание такого описания не будет overhead, а пользы принесет команде намного больше. Если не согласны, прошу в комментарии.