This 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 ...

Context

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

1. Write some french documentation explaining/paraphrasing agile architecture documentation
2. Create a maven artifact project containing smart tools allowing my colleagues - and myself - to easily produce high quality architecture documentation at low cost.

I immediatly met some accidental complexities that I solved through ... well ... shenanigans.

Asciidoc is not so easy

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.

Chaining Java code is not so easy

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

• Generate a basic architecture model of my application using Java code
• Augment that model with informations extracted from that model metadata
• Augment documentation with informations also extracted from that model metadata
• Generate an include chain allowing human-written documentation to include all that generated content
• Generate the correct diagrams

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).

A chain is as strong as its weakest link

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)

The final nail

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)

simonbrown Simon Brown 2 juil. 2021 à 09:57:18 A couple of people have asked whether Structurizr Lite can be used with the code-based client libraries. Absolutely! And since Lite is file-based, you don't need to use the API ... just export your workspace to a JSON file instead. More details at https://t.co/ITf3hiWrGx

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.

Time for introspection

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.

Isn't it anything to salvage ?

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

The good

• Provided I'm working on a monolith, I can assume maven modules are mapped to structurizr containers, and this helps producing immediate understanding of the project architecture
• Collecting informations from the maven model to augment the structurizr architecture model is really useful for developers : I don't have to indicate Structurizr it's a Spring project, as my code is already able to understand that by scanning dependencies
• In the same fashion, extracting GitHub conventionnal project files (README.md, CONTRIBUTING.md) is a great idea, as developers are used to fill those files with great content, that has its own place in architecture documentation
• Speaking of GitHub extraction, I played with the idea of using GitHub token to connect to GitOps repository to extract K8s deployment files and transform them into standard architecture documentation. This was poorly made, but already understandable AND useful

The bad

• As I already mentionned, build asciidoc content in maven, when using some plugins and wanting modern versions, is just a nightmare. The build file becomes very fast huge, and nobody can maintain a maven pom cumulating 5 profiles, 3 different plugin configurations - each using hundred of lines of XML). Beware : it's not a critic of Maven, more a citic of the non-optimal integration of Asciidoc in the maven way (yeah I'm a believer)
• Using another plugin system in a maven build is just plain stupid
• For the first time, I decided not to deliver my artifacts on maven central (due to the needed bureaucracy) but on Jitpack. It was a bad iead, since companies tend to maintain maven mirrors which mirror maven central (cool), possibly Spring repository (of no interest to me), but never Jitpack, which is way too volatile. So I couldn't download my artifacts in CI machines, and one of the promise of Structurizr (considering the architecture documentation as one of project by-products, always generated on build, and as a consequence alays up-to-date and available ina rtifact repositories)

The weird

• Being able to reuse architecture diagrams in reveal.js diagrams (thanks to asciidoctor-reveal) was quite funny, but was hardly used (which is quite normal, to my mind)
• I built a quite complex system to hide the Asciidoc content I generate, and I still can't decide if it was a genius idea, or the weirdest fuckery I've ever produced

What to do next

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 ?

• Use build-time analysis to enhance Structurizr models
• Use build-time analysis to also enhance produced documentation
• Integrate as much as possible in Structurizr ecosystem

And what are my non-goals

• Force users to choose between enhancements and conformance to Structurizr tooling
• Produce a virtual power plant, too complex to maintain
• Multiply the moving parts

I think I'm gonna try to use Hacktoberfest to rewrite my tooling in a smart way ...

Vous connaissez cette phrase ? Vous l'avez sans doute déjà entendue, parce que c'est un slogan de campagne qui a eu un certain succès. Mais pourquoi je mentionne ce slogan ? (on va venir doucement au coeur du sujet, installez-vous au coin du feu, et laissez-moi vous raconter cette fable)

Parce que si l'homme est une créature de chair et de sang, l'entreprise est une créature de pouvoir et d'argent. Je ne sais pas si vous avez lu Sapiens (personnellement, je n'en ai lu que la version dessinée), mais l'auteur énonce à un moment une idée forte

Yuval Noah Harari - Sapiens

Toute coopération humaine à grande échelle – qu’il s’agisse d’un État moderne, d’une Église médiévale, d’une cité antique ou d’une tribu archaïque – s’enracine dans des mythes communs qui n’existent que dans l’imagination collective. […] Pourtant, aucune de ces choses n’existe hors des histoires que les gens inventent et se racontent les uns aux autres. Il n’y a pas de dieux dans l’univers, pas de nations, pas d’argent, pas de droits de l’homme, ni lois ni justice hors de l’imagination commune des êtres humains.

Autrement dit, l'entreprise est une fiction entretenue par le pouvoir de ceux qui la créent (pensez par exemple à Steve Jobs, Jean-Marie Messier, Carlos Ghosn) et elle existe grâce à la circulation de l'argent qui lui vient de ses clients pour subvenir à ses besoins (salaires, fournisseurs, actionnaires, achats divers, ...). La différence importante entre une entreprise et un corps réel est que, comme il s'agit d'une fiction, il est aisé de confondre les moyens et les fins. C'est-à-dire qu'il est facile de croire que l'objectif d'une entreprise est de gagner de l'argent. Gagner de l'argent est pour l'entreprise l'équivalent de se nourrir à satiété : avec suffisamment d'argent, l'entreprise peut payer tous ses besoins et envisager de s'étendre, tout comme suffisamment de nourriture permet à un humain de réfléchir à améliorer son mode de vie. Pourtant, bien peu d'humains considèrent que leur but dans la vie est de disposer de suffisamment de nourriture. Dans la France du XXIème siècle, en dehors des gens sous le seuil de pauvreté, se nourrir est rarement un but prioritaire. C'est ce qu'exprime la (désavouée) pyramide de Maslov. Une telle pyramide des besoins existe-t-elle pour les organisations ? (je ne trouve pas, ça ne veut pas dire que ça n'existe pas, ça veut plutôt dire que la terminologie doit être différente)

On voit bien, pourtant, qu'il existe des besoins d'entreprise au-delà de "survivre" (qui se traduit par "gagner assez de l'argent"). Je citerai par exemple le besoin de vision : savoir ce que fait ou veut faire une entreprise est un besoin crucial, ne serait-ce que pour que les salariés puissent s'aligner avec cette vision, pour être capable de produire de la valeur sans avoir besoin d'instructions explicites. Sauf que construire une vision, ça nécessite une chose : comprendre le métier de l'entreprise et être capable de prendre, dans ce métier, une position claire.

(et maintenant, c'est le moment qui fait mal)

Reprenons donc mon article sur la structure du marché informatique en France.

Et regardons, à la lumière de cet article, le top 250 des entreprises SYNTEC. Qu'est-ce qu'on y voit ? Une domination évidente en nombre et en chiffre d'affaire des ESN. Pourquoi dominent-elles à ce point ce classement ?

Parce qu'être éditeur nécessite une vision, dont sont souvent incapables les dirigeants de ces entreprises (je vais me fâcher fort avec mon chef, là, #NotAllESN toussa toussa). En effet, pour produire un logiciel et arbitrer les envies de ses clients, il faut nécessairement se positionner d'une manière bien plus complexe que ce que font les grosses ESN qui se contentent de répondre à tous les appels d'offre, parce qu'elles ont un besoin terrible de faire circuler l'argent en leur sein (autrement dit, leur taille les a rendues incapables d'agilité et d'évolution, comme dans agar.io). Et, comme une conséquence logique, leurs dirigeants ne sont plus des visionnaires, mais des gestionnaires. Des gens dont l'objectif unique, la vision, est simplement d'assurer la rentabilité attendue par les actionnaires. Et si ces entreprises sont incapables de travailler avec les petites et moyennes entreprises du monde de l'informatique, c'est sans doute à cause de ce fossé entre gestionnaire et visionnaire.

Et ce fossé, on le retrouve à un autre endroit qui fera grincer encore plus de dents.

Est-ce que vous vous souvenez du "I have a dream" de Martin Luther King ? Ou de JFK promettant un américain dans l'espace avant 1970 ? Ou de De Gaulle avec sa vision de la France libre ? J'imagine que vous me voyez venir avec mes gros sabots. Le monde politique lui aussi est devenu un monde de gestionnaire, pour des raisons un peu semblables au monde des chefs d'entreprise : il y a tellement de gens à qui rendre des comptes qu'avoir une vision y est un luxe impossible ... Enfin, c'est la théorie appliquée dans les écoles qui forment l'élite de la fonction publique en France (typiquement l'ENA).

La conséquence est logique : ministères et grandes entreprises se font confiance parce que ces lieux partagent une communauté de culture, communauté où l'innovation est considérée comme un jeu trop dangereux pour être joué. Je pourrais par exemple citer l'exemple historique de la voiture électrique, qui existe depuis 100 ans mais qui ne décolle que parce qu'un fou visionnaire s'y est lancé, ou celui de ces fleurons industriels des transports qui ont pour la plupart été mis sur une voie de garage, parce que si il y a bien un domaine où l'innovation est nécessaire - et risquée - c'est le monde du transport.

Au-delà de ces exemples, il me semble que le marché de l'informatique en France est un exemple trop parlant pour être ignorable. Citez donc une entreprise française d'informatique qui propose de l'innovation autre que de façade. Je vais juste me permettre de définir "innovation de façade". Pour moi, une innovation de façade c'est, par exemple, créer un réseau social quel qu'il soit : l'innovation ne sera pas technique, elle ne sera que dans l'usage. Et l'usage, surtout pour le grand public, c'est sans doute l'un des éléments sur lesquels il est le plus facile de créer une envie, et donc un marché. Au-delà de ces innovations de façade dont la french tech se gargarise, quelles entreprises informatiques françaises sont authentiquement innovantes ? Bien trop peu.

Parce que ces innovations se heurtent à des gestionnaires de tous ordres, pour lesquels l'innovation est un risque avant d'être une opportunité. Et parce que les gestionnaires confondent les moyens (le besoin de faire circuler l'argent dans l'entreprise) et les fins (avoir une vision qui permette à l'entreprise de continuer à faire circuler l'argent après la prochaine révolution technologique).

Saian_Supa Ronan L.F 16 sept. 2021 à 19:50:10 1er Chtijug depuis… bah un bout de temps maintenant !!! Ça fait plaisir :) #Java17 #Chtijug https://t.co/H2yVKZ0WYU

Et Rémi et José venaient nous parler de Java 17. Franchement, pour moi, c'est un super sujet.

Sauf que ....

Le chtijug peut offrir ce genre de soirée grâce à ses sponsors. Et l'entreprise dans laquelle je travaille actuellement, Zenika, fait partie de ses sponsors.

Du coup, j'avais le même problème que Logan

lhauspie Logan HAUSPIE 💻 16 sept. 2021 à 09:10:49 Dur de choisir mes habits ce matin. On dit que choisir c'est renoncer et perso j'ai choisi de ne pas renoncer... On se voit ce soir au @chtijug pour la session sur Java 17 sponsorisée par @ZenikaLille. https://t.co/URar1IlNA3

Et donc, hier soir, j'ai dû choisir. Et même si j'aime beaucoup Rémi et José, j'aime aussi beaucoup le chtijug, et le buffet qui a lieu après chaque conf.

Résultat, hier soir, pour moi, c'était soirée préparation de buffet.

J'ai donc fait amener par des collègues (merci encore à eux) toutes les boissons de la soirée (une centaine de bouteilles de bière, et une cinquantaine de bouteilles de soft). Puis j'ai cherché, avec l'aide de Younès d'Euratech, des frigos aux quatre coins du bâtiment pour rafraîchir un peu les bouteilles (parce que la bière chaude, c'est moins bon). J'ai ensuite eu un petit créneau pour voir José nous parler des nouvelles méthodes dans les streams (avec un exemple d'utilisation de mapMulti assez rigolo). Et je repartais pour accueillir les plateaux du buffet et commencer à installer tout pour que les spectateurs et els orateurs puissent se détendre au mieux. Résultat, pour moi, l'image qui symbolise le mieux ma soirée d'hier soir, c'est plutôt celle-là

chtijug Ch'ti JUG 16 sept. 2021 à 21:43:34 Et maintenant place au buffet. Merci @ZenikaLille https://t.co/vtvH6ncWwp

Et franchement, ça fait plaisir de refaire un chtijug, même si je n'en ai presque rien vu. Vivement le prochain !