Size: a a a

Архитектура ИТ-решений

2020 August 28

RT

Roman Tsirulnikov in Архитектура ИТ-решений
Andrew Nilove 💔
А есть в открытом доступе пример описания с PlantUML по уровням абстракций для реального проекта?
Нету.
В этом и беда с книжками по теме: реальную проектную документацию коммерческих компаний показывать нельзя, вот авторы и выдумывают разные PetStore examples с разной степенью отрыва от реальности.
У нас нету схем с разделением по уровням абстракций.
Схема рисуется под задачу и может включать себя как выскоуровневые блоки, так и низкоуровневые.
Например контекст интеграции систем с фрагментом учточнения до технологических компонент в отдельно взятой точке, в интересах конкретной задачи.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
https://docs.spring.io/spring-security/site/docs/current/reference/html5/#authz-voting-based сделан через Antora.org ?

в скрипте указан asciidoctor

непоняяятно...
источник

V

Vlad in Архитектура ИТ-решений
Это разметка для текста. Он может в include source code. Билд скрипт видит этот include puml, рендерит картинку из псевдо кода и подставляет её.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Это разметка для текста. Он может в include source code. Билд скрипт видит этот include puml, рендерит картинку из псевдо кода и подставляет её.
нет нет, какой приблудой была собрана эта спека гредлом? я не очень в технических подробностях... уже полез читать про asciidoctor
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
Andrew Nilove 💔
нет нет, какой приблудой была собрана эта спека гредлом? я не очень в технических подробностях... уже полез читать про asciidoctor
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
мы тоже используем его
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
т.е. сайт собирается уже на основе готовых adoc?
а можно автоматизировать генерацию самих adoc на основе еще чего-то, например исходников самого проекта в Java? организационные моменты пока оставим за кадром )
источник

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
нет нет, какой приблудой была собрана эта спека гредлом? я не очень в технических подробностях... уже полез читать про asciidoctor
Роман дал отсылку на конкретный плагин к gradle)

Джависты и котлинисты хорошо её знают.
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
зачем?
у нас такой задачи не стояло, исходник пишут люди
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Roman Tsirulnikov
зачем?
у нас такой задачи не стояло, исходник пишут люди
а файлы adoc тоже люди ручками пишут?
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
документ обычно пишется ДО кода и содержит довольно прикладные штуки. Поэтому нам генерировать из кода как-бы совсем неактуально.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Roman Tsirulnikov
документ обычно пишется ДО кода и содержит довольно прикладные штуки. Поэтому нам генерировать из кода как-бы совсем неактуально.
понял
источник

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
т.е. сайт собирается уже на основе готовых adoc?
а можно автоматизировать генерацию самих adoc на основе еще чего-то, например исходников самого проекта в Java? организационные моменты пока оставим за кадром )
Представляется тяжёлой задачей. Теоретически грэдл может вытянуть модель из бд и отрисовать её в puml. Но все остальное - человеко генеренный контент практически всегда.
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
Vlad
Представляется тяжёлой задачей. Теоретически грэдл может вытянуть модель из бд и отрисовать её в puml. Но все остальное - человеко генеренный контент практически всегда.
+1

К тому же документ часто содержит разные прикладные сценарии и описание предметной области. На код это ложится примерно никак.
источник

V

Vlad in Архитектура ИТ-решений
Vlad
Представляется тяжёлой задачей. Теоретически грэдл может вытянуть модель из бд и отрисовать её в puml. Но все остальное - человеко генеренный контент практически всегда.
Типы подсетей или логическая сегрегация компонент (или сервисов) - вряд ли получится хранить в JavaDoc
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
Vlad
Представляется тяжёлой задачей. Теоретически грэдл может вытянуть модель из бд и отрисовать её в puml. Но все остальное - человеко генеренный контент практически всегда.
к чему все это спрашиваю. Была задумка генерить adoc на основе исходного кода проекта в Java, т.к. есть проблема с постоянным рассинхроном между реализаций в Java и тем, что написано в спецификации требований (и позднее в базе знаний по проекту).
Т.е. при сборке автогенереной документации должно постоянно что-то ломаться и тем самым заставлять исполнителей вовремя вносить изменения в порядок сборки автогенеренной доки.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
например, тот же spotify рендерит живые файлы проекта и дока создана на 90% автогенеренкой

https://developer.spotify.com/documentation/web-api/reference-beta/
источник

V

Vlad in Архитектура ИТ-решений
Andrew Nilove 💔
к чему все это спрашиваю. Была задумка генерить adoc на основе исходного кода проекта в Java, т.к. есть проблема с постоянным рассинхроном между реализаций в Java и тем, что написано в спецификации требований (и позднее в базе знаний по проекту).
Т.е. при сборке автогенереной документации должно постоянно что-то ломаться и тем самым заставлять исполнителей вовремя вносить изменения в порядок сборки автогенеренной доки.
Видел плагины которые выковыривают javadoc и формируют подраздел в adoc. Проблема в людях: JavaDoc неказистые мануалы отразработчиков разработчикам.

Куда выгоднее смотреть в сторону интеграции cucumber и adoc. Плагин есть, но не тестировал.
источник

AN

Andrew Nilove 💔 in Архитектура ИТ-решений
но у Spotify случай попроще, т.к. они генерят на основе уже готовых Swagger файлов
источник

RT

Roman Tsirulnikov in Архитектура ИТ-решений
для докуентирования API из кода adoc использовать точно не стоит. Попробуйте SpringFox - генератор OpenAPI спецификации из Java кода
источник