24 septembre 2021
sourceThis article is of a kind I don't like : it's a failed experience feedback. And it's written in english for one reason (and only one) : making sure Simon Brown (whom I don't know french reading level) reads and understands it.
And what failed is a project I developped to leverage (at least that what I thought when I started) Structurizr ability at providing a lightweight model usable and editable by Java.
But first ...
I've discovered C4 and Structurizr some years ago (my external archive tells me it dates from '18). And I've immeditaly loved the way it allows someone to describe a software system architecture with an ease that UML never ever dreamed of. Not long after, I read the agile architecture documentation template provided by Simon and really felt in love (undoublty because I do believe humans are story people) with the way it tells the story of the software system studied using C4 and Structurizr.
So, when I was missioned as cross-team tech lead for three projects, I decided to use that tooling to produce all my documentation. And I was able, thanks to these tools and my old architect tool belt (PlantUML and Asciidoc) to produce architecture documents of a very good level with little effort. However, there were some Java classes used to extract informations from the environment (K8s deployment information) and from the build artifacts (maven modules as containers) that were too much specific to my mind.
Need is mother of invention
As a consequence, when the pandemic locked me at home with no more mission, I took the time to get my ideas together and
I immediatly met some accidental complexities that I solved through ... well ... shenanigans.
Figure yourself, generating asciidoc in Maven is not so simple.
Indeed, as Asciidoctor is not a Java port of asciidoc, but rather a wrapping of the Ruby code using JRuby, customizing that generation is quite complex. Typically, each component of the system must have a version that allows all the components to work together.So when you update JRuby, you have to check "religiously" that the asciidoct-maven-plugin still works, and that asciidoctor-diagram works.
Speaking of which I had to solve a very specific bug with what can only be described as a hack.
Considering I wanted to build a Java model of the code prior to feeding asciidoctor-maven-plugin with PlantUML diagrams generated from that model, I had to
The augmentation part being modular (the curse of architects) to handle different cases, such as projects using GitHub or Gitlab, extracting containers from Maven and components from Spring/GWT/JavaEE components, I chose to use an old friend of mine, CDI (and in that particular case, JBoss Weld).
And, since all that code was to be run in maven, I had wrap that Java executable in a call to exec-aven-plugin, with all parameters sent as system properties (which worked well, but was quite ugly in the maven pom).
So, my Java code started a Weld container, loaded all CDI components, and orchestrated it. All in a maven build which job is ... well ... to orchestrate plugins, no ? So the concept was good, but the implementation was overly complex.
What was more annoying was that, since my maven build had to embed the exec-maven-plugin code and the asciidoctor-maven-plugin generation (which used asciidoctor-diagram and "some" configuration to handle niceties such as ability to send feedback to documentation author), the pom.xml file was of a rarely seen size (692 lines for the project documentation module).
But there is even worse. Acustomed to old french companies, which tend to despise external tools, I prefered to use C4-PlantUML to output diagrams instead of sending them to a structurizr workspace. It worked well, thanks to structurizr-plantuml module (which I contributed to), until the accident. Well, not a real accident, but more an incident. As you see in that question, I found a solution (the hack previously mentionned). But even after having solved that issue, generating the PlantUML diagram remains painfully slow.
To be honest, in my current mission, generating asciidoc routinely takes more than 2 minutes, mainly due to diagrams (yup, i've tested removing them). And, due to the accidental complexity of my pom, i never did the move from asciidoctor-diagram to asciidoctor-kroki (which is way faster, and accept ay more easily to generate diagrams using a locally unning docker image)
I guess you see the end coming ... but, you know, I'm quite persistant. And I tried to fix that, but then came the final nail. This one took the form of an opportunity : replaying in an evening event the presentation I did in my company, which you can see below
And when I started working on it, I took a look at this intriguing Simon Brown tweet (because I was intrigued by the concept of structurizr-lite)
And it was a blast : I was able to write my model in a cute DSL, and have all my diagrams rendered nicely. This was a very good presentation tool (I tested it on my colleague), but also a way to generate those diagrams that was undoubtly wayyyy better packaged than what I was building.
I'm not good at introspecting as I tend to think i'm an awesome person, with genius ideas and the ability to deliver them flawlessly. But this time, the comparison was hard and I had to consider my frankenstein of a tool for what it was : a good idea, poorly delivered.
It took some time (and this article is the realization of this introspection), but I've finally understood that there were good and bad ideas.
Let me sum them up here
I tink this article quite sums up the next step : I should refocus on the parts of the project that adds value to Structurizr ecosystem, and give up the other fragments.
But, instead of immediatly giving a method (what I did in my first draft which I immediatly seen as wrong), I think I should first use agile architecture documentation lessons and redefine my goals and non-goals. So, what are my goals ?
And what are my non-goals
I think I'm gonna try to use Hacktoberfest to rewrite my tooling in a smart way ...