Опять выношу из чатика, мне показалось интересным. Минимальная редактура, чтобы лучше была видна оппозиция мнений.
Тема — архитектурная документация в компании и ее унификация. Я это видел часто и уверен, что на эти грабли натыкаются очень часто — пытаются унифицировать артефакты архитектурных описаний, сформулировать «стандартные» требования к ним, и все такое. Я уверен, что в 80% случаев от этого будет больше вреда, чем пользы. И вот как развивался диалог на эту тему. «Ответ» — это мои реплики. «Вопрос» — реплики собеседников, иногда разных.
Вопрос:
Какие артефакты для каждого из шагов системного дизайна вы считаете обязательными (минимально необходимыми, для того чтобы приступить к следующему шагу и в итоге к разработке)? Например:
Функциональный дизайн — сценарии использования, описание функций (как работает, какие ограничения, какие параметры) и объектная модель (модель данных на уровне бизнес объектов, не разложенная по плоским таблицам)
Архитектурный дизайн — HLD (слои, компоненты, грейды и свойства компонентов), Workflows (взаимодействие между компонентами поверх HLD)
Системный дизайн (API/Events, диаграммы последовательности и схема данных + маппинг в случае интеграционных компонентов)
То есть мы пишем сценарии, на них выявляем функции и описываем их, из функций определяем необходимые объекты и описываем их. Затем раскладываем объекты и функции по компонентам, и на основе сценариев строим флоу межкомпонентого взаимодействия. После этого определяем интерфейсы для каждого из компонентов (на основе флоу), к каждому интерфейсу рисуем сиквенс, и в итоге раскладываем объекты из функционального анализа на плоские таблицы.
Подход показывает эффективность в случае распределенных систем, с монолитными все чуть сложнее (структуры данных там запутаней и функции менее инкапсулированы) и не всегда этих артефактов достаточно (часто требуется диаграммы классов).
Как вы строите флоу и какие артефакты считаете минимально необходимыми, чтобы каждый из этапов резал максимум рисков?
Ответ:
Такие, чтобы команда(-ы) разработки не ушла в неправильную сторону. Если сроки жесткие, то действуем не по шаблончикам и списочкам, на это нет времени, а по живой коммуникации с каждой командой. Новый артефакт добавляется в конкретном месте тогда, когда видна его необходимость, а не «чтобы был».Т.е. когда видно, что лиды плохо понимают, буксуют, не могут декомпозировать дизайн на задачки для спринтов. Конечно, с чего-то можно начать и заранее, но обычно времени хватает только на минимум. И конечно, очень зависит от характера проекта. В одном — сплошные sequence diagrams, потому что в них основная сложность. В другом проекте их нет вообще, не нужны, все по-другому работает, зато акцент на маппинг данных в разных системах. И от компетентности команд, конечно, тоже зависит. Одним нужно все разжевать и в рот положить, другие сами у тебя рвут шапку архитектора и готовы дизайн отдельных сервисов придумать и описать сами.
Вопрос (с неожиданным переиначиванием смысла):
Ок, для небольших команд это ок, но когда у тебя 5-10 команд по 5-10 человек в каждой (что в целом тоже относительно небольшая команда) без документации не получится жить. Онбординг новых разработчиков и тем более архитекторов или аналитиков проходит всегда через артефакты. И артефакты функционального анализа тут не столь важны, но они при разработке режут самое большое количество рисков.
Ответ:
А кто сказал «без документации»? Вроде как раз обсуждали, _какая_ документация нужна. Контекст, задачи, и проблемы определяют, какая нужна коммуникация и какая документация будет помогать в этой коммуникации.
Вопрос:
Так вопрос в минимально необходимой документации — она не может быть разная в рамках компании или продукта.
Ответ:
Почему? Скорее всего, если она не будет разная, то она не является «минимально необходимой» 😉
Вопрос:
Разная документация на разные компоненты убьет любой онбординг. Для этого можно было прийти почти в любой банк 5-7 лет назад и понять что базу знаний можно впринципе не смотреть
Ответ:
Если искать «минимальный объем документации, который будет общий для всех и при этом которого будет всегда хватать», то получится как раз довольно много и в половине случаев будут неиспользуемые артефакты.
Можете объяснить механизм, каким образом «убивается онбординг», если мы про каждый компонент рассказываем самое важное, а не все по списочку?
Вопрос:
В примере выше какие артефакты не будут использоваться? Даже в случае какого либо фасада или адаптера.
Ответ:
Нельзя ответить абстрактно на этот вопрос 🙂 Если бы я мог, это бы значило, что какой-то артефакт не нужен никогда, а это неправда. Когда-то может и нужен.
Вопрос:
Для каждой роли буду важны свои арты. Документацию читают не только разработчики. А если в разных компонентах разные арты, с течением времени точно произойдет конфликт между артами и ты не сможешь связать львиную часть флоу. Особенно если команд несколько и каждая работает по своим стандартам.
Ответ:
Понятно, что потребители разные. Но это не умаляет мой тезис никак: «минимально необходимая документация» несовместима с «стандартизованным набором артефактов». Выберите что вам милее.
Вопрос:
Минимальный набор не должен отличаться от компонента к компоненту, только если тип компонента отличается. Для адаптеров не нужны сиквенсы и схема данных, там нужен маппинг.
Не потому что что то лучше/хуже, а потому что эти артефакты ничего не опишут.
Ответ:
Ну может не для самого «адаптера», а для нескольких компонентов, включая «адаптеры», _если_ они реализуют нетривиальное по последовательности взаимодействие, чтобы его можно было понять. Да и про маппинг — одной команде надо реально пример SQL написать, иначе накосячат сто пудов, для другой это будет совершенно лишнее. Если у вас все однотипное, и компетенции тоже выровнены — ваше счастье, стандартизация принесет больше пользы и меньше вреда. Но не всегда так, и уж точно не так от компании к компании. Стандартизация, внедряемая при большом разнообразии, может принести больше вреда. А «минимальное необходимое» всегда предельно контекстуально, по месту, иначе оно не будет минимальным.
Вопрос:
Думаю, тут вопрос в том, что автор ‘самого важного’ по своей компоненте может не знать/не учесть, что важно разным пользователям документации с других команд (если их много и они не сильно общаются друг с другом, что часто в средних и больших организациях), а в случае ‘по списочку’ разработчики формата доки это учтут. То есть то, что уберет основные риски взаимодействия разных команд в разрезе всей организации , и является ‘минимально необходимой документацией’ (а не только то, что владелец компоненты субъективно считает ‘концептуально важным’)
Ответ:
Ну то есть мы изначально предполагаем, что коммуникация не налажена или отсутствует, чинить это не хочется, а избыток документации должен это компенсировать? Инженерный подход 🙂 Боюсь, вы не прочитали то, что я противопоставлял этой идее. Не то, что «владелец посчитает важным» — это опять было бы свидетельством разорванной коммуникации — а то, что реально важно, т.к. проявляется как проблема. Я говорил тогда про взаимодействие архитектора и команды разработки, там расстояние меньше и время короче и взаимодействие теснее. С межкомандной документацией проще в том смысле, что там нужны больше черные ящики — API, внешние структуры данных, такое. Но сложнее в том, что потребителей больше, взаимодействия реже, коммуникация не такая плотная. Но общий принцип того, что документация это только один из инструментов для построения коммуникации — сохраняется. Если задаться вопросом, легко можно узнать, какой документацией пользуются, а какой — не хватает. Запросить обратную связь, устроить митап, сходить ногами и поговорить. Что-то можно включить и в стандарт, конечно, для того или иного типа API, если абсолютно понятно, что это необходимо. Но все-таки в целом я бы рекомендовал стандартизовывать и требовать наличие процессов коммуникации и удовлетворенности потребителей этой коммуникацией. А документация подтянется как следствие, причем именно та, которая нужна и востребована, а не «по стандарту».
Вопрос:
По идее, именно такой подход и приветствует agile, который почти везде и который требует общаться средствами кроме документации (попутно требуя с суровых тех.спецов вместо умения печатать срочно-обморочно развивать умение общаться и прочие софты, что тоже , замечу, и время, и ресурсы, и силы, и , в отличие от написания доков- сильно не гарантированный результат из-за человеческого фактора).
В итоге, многие из них сейчас пришли к выводу, что agile хорошо, но дока нужна полная (не путайте с избыточной) и ее вернули в корп.культуру 😉
Ответ:
И опять мне не удается донести главную мысль, и считывается неверно. Никто не предлагает заменить личным общением документацию. Документация — очень эффективный инструмент коммуникации, тупо его не использовать. Тезис совсем в другом: наша цель — организовать эффективную коммуникацию. Эффективная коммуникация является в данном случае целевой системой. Документация будет являться составляющей частью этой системы, скорее всего и чаще всего — необходимой частью. Личное общение также очень полезно как составляющая часть коммуникации. Но отношение именно такое — коммуникация как система, документация и общение и другие способы коммуникации — как элементы, части, инструменты. Ну и далее — главный принцип — проектирование и оптимизацию ведем от целого, а не от части. Поэтому сперва смотрим на целое — кто участники коммуникации, какие особенности времени и места и контента, какие есть ограничения, какие целевые показатели качества этой коммуникации, какие есть проблемы. А после этого спрашиваем: какие нам нужны части/инструменты в организации коммуникации, чтобы стало лучше?
Кстати, хорошее замечание про софт-скиллы инженеров и естественные барьеры к общению. Так вот это тоже надо класть как объективные свойства человеческого материала при орг-проектировании и думать, как нивелировать негативный эффект, не ломая людей, и все же обеспечить эффективную коммуникацию. Решение — «только документы» — скорее всего, сильно неоптимальное.
Но снова и снова собеседники ошибочно полагают, что коммуникация — это и есть «личное общение» и противопоставляют коммуникацию документам.
Вопрос:
В общем, в случае с докой, понятно, что это нудно, но экономить и надеяться на налаженные коммуникации не стоит, потом чаще всего выходит дороже)
Подведем итог
Запомните это как мантру: документы и другие артефакты — это инструмент в коммуникации
Для развития системного мышления очень полезно начать мыслить коммуникацию как систему, абстрактное взаимодействие с целью передачи некоторых знаний/решений/etc.
После этого — думать, какая именно коммуникация вам нужна там или тут, какие есть у вас проблемы там или тут в коммуникации. Например — кто о чем узнает поздно? Кто оказывается дезинформирован? Когда обнаруживается, что знания доступны только с человеком и это становится проблемой и почему?
Когда вы сможете ответить на эти вопросы, можно переходить от функционального анализа/проектирования к чему-то более физическому — разговаривать про инструменты коммуникации — документы, диаграммы, видео, белые доски, личное общение, чаты, базы знаний, и т.п.
И попробуйте вместо стандартов на артефакты сделать стандарт на направления и качество коммуникации. А уж какими артефактами она будет поддержана в каждом конкретном случае — может быть весьма ситуативно. Полезно иметь альбом шаблончиков, для того, чтобы участники могли подобрать что-то, что им подойдет, как tool box. Но не как стандарт, за исключением ну очень одинаковых и типовых ситуаций. Например, может быть стандарт на описание синхронных HTTP-based API, но никак не стандарт на описание архитектуры систем, если вы занимаетесь самой разной прикладной разработкой.
Точнее, стандарт уже есть — ISO 42010, и конечно же, главное, что он предписывает — это предельную контекстуальность описания архитектуры. Какие модели выбирать — определяется перечнем читателей-интересантов, а что им нужно, и удалось ли ответить на их вопорсы — вы узнаете только в коммуникации с ними.