или Что бы сказал Говард Рорк, увидев наш раздел "Архитектура"?

Вы можете спросить "при чём тут этот архитектор из романа "Источник" Айн Рэнд?" и я отвечу: Рорк искал смысл в каждой мелочи. Всё должно иметь смысл. Не может быть статьи в документации, которая ничего не даёт команде проекта. Не может быть бессмысленных фраз и пустых обещаний. Всё должно служить главной цели, а не создавать шум или туман.

Я сейчас читаю книгу "Проектирование архитектуры API". Тема для меня интересная, и в процессе чтения не просто хочется разобраться как что устроено, чтобы потом применять эти знания на практике, но главное - понять, как улучшить свою собственную работу и строить процессы в лучших практиках. Дойдя до упоминания ADR (Architecture Decision Record, записей архитектурных решений) в книге, я задалась вопросом:

"А есть ли на проекте, в котором я сейчас задействована в роли системного аналитика, раздел с ADR в confluence?".

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

И действительно - оказалось, что раздел Архитектурных решений существует! Однако, я столкнулась с шокирующим открытием. Дело в том, что выяснилось сразу несколько чудовищных фактов вообще о разделе "Архитектура":

1. Об этом разделе знают единицы. Бизнес-эксперты его никогда не видели. 2. Текст в большинстве статей сгенерирован ИИ, изобилует сложными терминами. Чтобы понять, что там написано, нужен словарь. 3. Схемы архитектуры не актуальны. У статей со схемами нет даже заголовков и оглавления. 4. Коды в заголовках не дают понимания о содержимом.

Но вернёмся к вопросу об ADR. Среди десятка статей об архитектурных решениях была одна, которая непосредственно касалась разрабатываемых мной требований. В этом ADR был описан контракт взаимодействия с внешней системой — перечень полей. И одно из полей не просто выбивалось из общей массы — оно ломало саму логику сущности, которую мы передавали. Я связалась с бизнес-экспертом и выяснила, что об этом поле никто не слышал. Связавшись с человеком, который сменил ушедшего архитектора, я выяснила также, что сам этот контракт - "плод воображения", "фантазия", и что мне предлагается привести ADR в соответствие с тем, что мы реально передаём! Вот такой поворот.

Вот она — архитектура без смысла. Декорация вместо здания. Что бы сказал Рорк, увидев это? Думаю, он бы сказал: этому разделу недостаёт сути.

Но как я - системный аналитик - могу этот смысл тут увидеть или прибавить? Что делать, если сам раздел совершенно заброшен и не отвечает на вопрос "как всё устроено?". Готовых ответов у меня нет. Но первое, что я предложила сделать новому архитектору - это актуализировать архитектурные схемы, добавить крупные заголовки в статьи, а главное - в головной статье с архитектурными решениями написать "по-человечески" - что такое ADR, зачем это нужно и почему это важно. Чтобы член команды, зашедший в этот раздел, сразу мог понять что он видит перед собой, даже если до сего дня не сталкивался с термином ADR. Архитектор согласился со мной и я добавила такую краткую вводную часть в статью. Теперь можно постепенно двигаться дальше и добавлять потерянный смысл - шаг за шагом. Ведь суть документации не в том, что она есть, а в том, что она должна служить команде, а не наоборот.

А у вас документация служит команде? Были случаи, когда находили в ней "призрачные" сущности?

#архитектура #документация #аналитика