Не так давно, мне пришел вопрос от подписчика, ответ на который превратился аж в небольшую статью :)

Руслан, привет!) а подскажи пож-та, может есть у тебя ссылочки на шаблоны/примеры/лучшие практики по документированию архитектуры и инфраструктуры системы

Вопросы документирования и особенно актуальности документации — на мой взгляд, одни из самых больных в нашей с вами айтишечке. Но, если дело касается сущностей, которые мы можем описать кодом (или как код) — всё становится сильно проще.

1. Лучшая документация — это всегда актуальная документация. Такой вариант возможен только в двух случаях:

   • при автоматической генерации документации (описания) из реального положения дел (для исполняемого кода API таким примером будет Swagger)

   • или же наоборот — генерации "реальности" из описания (в случае Infrastructure as Code примером может быть разворачивание инфраструктуры из её описания в yaml-формате).

2. Если лучший вариант нам недоступен, то хорошо бы нам хотя бы иметь автоматический сигнал о том, что наша документация разъехалась с реальностью (или наоборот) ?

   Источником такого сигнала должны стать тесты — мы их можем и будем запускать при любом изменении и системы (реальности), и её описания. И в случае расхождения тесты должны падать (блокируя тем самым дальнейшее попадание порождающих несоответствие изменений в основную ветку/новый релиз и т.д.).

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

3. А вот третьего, на мой взгляд, не дано. Либо у вас есть автодокументация, либо есть автоматизированные тесты, проверяющие актуальность. В противном случае — всё, ваша документация рано или поздно в бо́льшей или меньшей степени, но станет неактуальной. Без вариантов. И никакими оффлайн-процессами или регламентами это не решить. Есть, конечно, ещё один граничный случай — это когда в проект никаких изменений не вносится.. Но это означает, что проект мёртв, и этот случай нам неинтересен ?

Итак, возвращаясь к архитектуре и инфраструктуре.

Начнём с инфры. Если у вас реализован подход Infrastructure as Code (IaC) и всё разворачивается из кода (описания) инфры — то уже всё хорошо. По сути ваши yaml или другие файлы и являются документацией (сюда попадает не только статичная инфра, но и различная инфраструктурная логика: мониторинг и правила алертинга, например). А если хочется иметь документацию по инфраструктуре в более удобном и наглядном виде — всегда можно написать различные генерилки/визуализаторы из yaml и json в красивый текст и схемки (или даже интерактивный, как у Swagger). А возможно, такие инструменты уже и существуют (накидайте, плиз, если да).

С архитектурой всё чуть сложнее. Подход Architecture as Code (AaC) в отличие от IaC не предполагает, что по описанной в коде архитектуре всё будет разворачиваться и работать согласно ей. В большинстве случаев предполагается лишь описание архитектурных схем кодом из которого генерируется картинка, а не просто картинкой. В таком случае Architecture as Code на самом деле всего-то навсего Architecture Scheme as Code ?. Т. е. не сама ИТ‑архитектура, а лишь опять же её документация в виде схемки или нескольких.

Тут некоторые читатели могут задаться вопросом — а что же такое ИТ‑архитектура, если не просто схемка или набор схемок?

Готовясь к одному из своих докладов, я гуглил разные определения ИТ-архитектуры. И к своему удивлению нашел одно из лучших, на мой взгляд, в стандарте ANSI/IEEE Std 1471-2000:

Фундаментальная организация системы, реализованная в её компонентах, их взаимоотношениях друг с другом и средой и принципах, определяющих её конструкцию и развитие»

Т.е. архитектура — это даже больше чем просто "описание реальности" как IaC, но и принципы, определяющие в том числе и её развитие (т.е. будущее). Но сейчас не об этом... Про то, что такое архитектура надо будет как-нибудь отдельный пост написать ? (и это на 4й-то год существования моего телеграм-канала со словом "архитектура" в названии ??).

Скрепя сердце и приравняв архитектуру к документации, вернемся к вопросу актуальности этой документации. Описав архитектурные схемки кодом (т.е. применив AaC) мы можем пойти описанными выше путями в плане автодокументации или тестов на актуальность, но для этого нужны ещё инструменты над AaC (см. ниже). Т.е. всё-таки as Code нам помогает, хоть и в меньшей степени, чем в IaC, где as Code уже гарантирует соответствие реальности и описанию (коду).

Вот так, размышляя о документации, мы пришли к выводу о различии подходов, называемых as Code в инфраструктуре и архитектуре ?

А теперь обещанные ссылки на мои инструменты:

• разделы Open-source репозитория с инструментами и примерами:
  

  • автогенерация архитектуры

  • тесты на актуальность архитектуры

• статья про покрытие архитектуры тестами (статья-победитель технотекста 2023 ??):

• общий доклад про все инструменты:

P.S. Оффтоп. И всё-таки, согласно в том числе и определению из стандарта, архитектура — это в том числе и принципы на которых она построена, а один из способов описания таких принципов (ещё и сразу же автоматизирующий проверку их выполнения) — это тесты на соблюдение архитектурных принципов.

Всё. Теперь точно всё )
❤️