diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a788f8b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,136 @@ +# Style d'écriture + +## Deux registres distincts + +Le blog contient deux types d'articles qui n'obéissent pas aux mêmes règles : + +**Articles d'opinion / éditoriaux** (ex. : *La complexité est devenue la solution paresseuse*, *L'architecture pragmatique de mes projets*) : +- Ton personnel, première personne du singulier ("je") +- Phrases courtes et rythmées, parfois elliptiques +- Titres de sections affirmatifs ou interrogatifs à fort impact +- Anecdotes personnelles pour étayer les arguments +- Questions rhétoriques pour interpeller le lecteur + +**Articles tutoriels / techniques** (ex. : *Whiteout files*, *IPv6 dans Docker*, *Auto-hébergement*) : +- "On" acceptable et même préférable quand il désigne le lecteur en train de suivre les étapes +- Ton instructionnel, pas d'interpellations rhétoriques +- Sections structurées en étapes logiques +- Blocs de code avec prompt spécifique : `42sh$` pour l'hôte, `incntr$` dans un conteneur +- Notes d'information ou d'avertissement avec le shortcode `{{% card color="info/danger/success" title="..." %}}` +- Footnotes `[^clé]` pour les références et sources + +## Caractéristiques communes aux deux registres + +- **Registre soutenu mais accessible** : le texte s'adresse à des techniciens sans être hermétique. Pas de jargon inutile, mais une exigence dans la formulation. +- **Anecdotes personnelles** : les arguments s'appuient sur des expériences vécues concrètes. +- **Structure forte** : les articles sont toujours découpés en sections clairement titrées. +- **Liens enrichissants** : liens internes avec `{{< relref "..." >}}` et liens externes vers les outils ou sources mentionnés. + + +## Corrections à appliquer systématiquement + +### 1. Pronom personnel + +**Dans les articles d'opinion** : remplacer le "on" par "je" quand c'est l'auteur qui parle. + +- ❌ `on peut générer un système entier` → ✅ `je peux générer un système entier` +- ✅ `on copie les architectures de Netflix` (le "on" est correct ici, il désigne l'industrie) + +**Dans les tutoriels** : "on" est correct quand il désigne le lecteur qui suit les étapes ("on relance Docker", "on vérifie que..."). + +Le "on" reste valide dans les deux registres quand il désigne une pratique collective ou l'industrie en général. + +### 2. Registre des formulations + +Éviter les tournures relâchées ou familières au profit de formulations plus soignées. + +- ❌ `Pourquoi il n'y a pas Kubernetes ?` → ✅ `Pourquoi n'y a-t-il pas Kubernetes ?` +- ❌ `utiliser le système de fichiers comme ça` → ✅ `utiliser le système de fichiers ainsi` +- ❌ `ça valorise une carrière` → ✅ `valorise une carrière` +- ❌ `c'est que ce n'est pas si compliqué` → ✅ reformuler en phrase affirmative directe + +### 3. Anglicismes évitables + +Préférer les équivalents français quand ils existent et sonnent naturellement. + +| À éviter | Préférer | +|---|---| +| start-up | entreprise qui démarre | +| IA / outils d'IA | intelligence artificielle / logiciels d'intelligence artificielle | +| CPU | processeur | +| briques | composants | + +Les anglicismes techniques sans bon équivalent restent acceptables (*custom*, *service mesh*, *micro-services*). + +### 4. Affirmations sans hésitation + +Éviter les formulations qui affaiblissent le propos quand le texte assume une position. + +- ❌ `il me semble que la paresse se situe ici` → selon le contexte, peut rester pour nuancer, mais à utiliser avec parcimonie +- ❌ `on pourrait dire que` → ✅ dire directement +- Les titres de sections doivent être affirmatifs, pas interrogatifs sur le fond + +### 5. Transitions en début de phrase + +Éviter les chevilles faibles en début de phrase. + +- ❌ `Et c'est là que...` → ✅ reformuler directement +- ❌ `Mais c'est précisément...` → ✅ commencer par le sujet +- ✅ `Autrement dit,` est une bonne charnière de reformulation + +### 6. "Très" et intensificateurs inutiles + +Supprimer les adverbes qui n'ajoutent pas de sens. + +- ❌ `extrêmement complexes` → ✅ `complexes` +- ❌ `très courant` → ✅ `courant` +- ❌ `très simple` → ✅ `simple` +- ❌ `beaucoup plus simple` → ✅ `plus simple` (sauf si l'insistance est vraiment nécessaire) +- ❌ `fonctionnait très bien` → ✅ `fonctionnait bien` ou reformuler + +### 7. Découpage des phrases longues + +Quand une phrase contient plus de deux propositions, envisager de la couper. + +- ❌ `Certes le cœur est devenu un produit générique, mais tout ce qu'il y a autour : l'orchestration, les scripts, le scotch, les adaptations, sont devenus le nouveau custom.` +- ✅ `Certes, le cœur du système est devenu un logiciel générique.\nMais tout ce qui le complète — l'orchestration, les scripts, les adaptations — est devenu le nouveau *custom*.` + +### 8. Interpellation du lecteur + +Ajouter ponctuellement une courte phrase d'interpellation après une affirmation forte, pour briser le rythme et créer de la connivence. + +- `Cela vous parle ?` +- `Cela vous semble logique ?` +- `Devinez quoi ?` + +Ne pas en abuser : une ou deux par article suffisent. + +### 9. Structure des listes + +Dans les énumérations à la première personne, veiller à la cohérence du pronom. + +- ❌ mélanger `on sait` et `je comprends` dans la même liste +- ✅ choisir un pronom et s'y tenir pour toute la liste + +### 10. Reformulations personnelles et narratives + +Éviter les formulations passives ou impersonnelles au profit d'une narration active à la première personne. + +- ❌ `J'ai donc déplacé la partie publique` → ✅ `Ma solution a consisté à déplacer la partie publique` +- ❌ `Lorsqu'on lit certaines discussions` → ✅ `Lorsqu'on lit` reste valide ici (désigne les lecteurs en général), mais préférer `je` dès que c'est l'auteur qui parle + +### 11. Vocabulaire technique plus précis + +Préférer les termes les plus précis et les moins galvaudés. + +- ❌ `cluster Kubernetes` → ✅ `environnement Kubernetes` +- ❌ `pipeline CI` → ✅ `processus de génération` ou `chaîne d'intégration` +- ❌ `utilisateur →` dans les schémas d'architecture → ✅ `navigateur →` (plus précis techniquement) + +### 12. Structure des titres de sections + +Dans Hugo, les titres de sections d'article utilisent `##` (pas `#`, réservé au titre principal du document). + +### 13. Enrichissement par les liens + +Les articles gagnent à être enrichis de liens internes avec `{{< relref >}}` vers d'autres articles du site, et de liens externes vers les outils ou sources mentionnés. Ne pas hésiter à en ajouter quand un outil, un projet ou un article connexe est mentionné. diff --git a/content/en/post/complexity-is-the-lazy-solution/index.md b/content/en/post/complexity-is-the-lazy-solution/index.md index 13ee532..6def3ca 100644 --- a/content/en/post/complexity-is-the-lazy-solution/index.md +++ b/content/en/post/complexity-is-the-lazy-solution/index.md @@ -8,186 +8,199 @@ tags: - cloud --- -In software engineering, complexity is often seen as a sign of professionalism. +In software engineering, complexity is often seen as a sign of competence. -A simple system looks suspicious.\ -A complex system looks serious. - -Yet my experience has repeatedly shown the opposite. +Indeed, a simple system looks suspicious, while a complex system looks serious. -## A decade of success is not enough to convince +## What is the value of a decade of success? In my final year of engineering school, I built a CTF platform. -At the time, no tool like CTFd existed. +At the time, no software like [CTFd](https://github.com/CTFd/CTFd) existed. Everything had to be built from scratch. -I made simple choices: serve static files to reduce the attack surface, generated on demand; classic Unix services glued the pieces together, low-level containers isolated services from one another. +It took me a lot of thinking to arrive at an architecture that looks simple in hindsight: serve static files, generated on demand, to reduce the attack surface. +Standard Unix services glued the components together. +Low-level containers isolated services from one another. The first year was a bit chaotic, as any first attempt tends to be. -But iteration after iteration, the system stabilized. +Improvement after improvement, I managed to stabilize the system. A few well-scoped micro-services came to structure the critical parts. -And for ten years, it ran like clockwork. +For ten years, the whole thing ran like clockwork. No major incidents. No outage caused by a poorly understood service going down. -Yet every time I presented the architecture, I ran into the same questions: +Yet every time I presented the architecture, I heard the same questions with a skeptical tone: - Why isn't there Kubernetes? -- Why are you using the filesystem like that? -- Why isn't there a REST API? +- Why use the filesystem that way? +- Why not a simple REST API? -I never managed to convince anyone. +Here is the answer to the question about the value of a decade of success: I never managed to convince anyone. +A decade of success was not enough. When I left, my work was thrown away. -The new solution is built on CTFd: a generic product that requires far more computing power, offers fewer features, and runs on Kubernetes, of course. +The new solution is built on CTFd. +In other words, a generic product that requires more computing power, offers fewer features, displays an austere interface, and runs on Kubernetes, of course. -Since then, I keep asking myself the same question: **why does the software industry value complexity over simplicity?** +Since then, I keep asking myself the question: **why does the software industry value complexity over simplicity?** ## Complexity has become the default reaction -Today, faced with a technical problem, the instinctive reaction is almost always the same: add more. +Today, faced with a technical difficulty, the reaction is almost always the same: add more. More machines, more software layers, more cloud, more abstractions. CPU at 100%? Add more CPU.\ -The system is slow? Migrate to the cloud.\ -The architecture doesn't look right? Switch to microservices. +The system is slow? Move everything to the cloud.\ +The architecture doesn't suit anyone? Switch to microservices. -But these decisions are often made before anyone has understood the problem. -**When a system becomes slow, the modern reaction is to add servers. An engineer's reaction should be to ask why.** +According to my observations, these decisions are often made before anyone has understood the problem. +**When a system becomes slow, the instinctive reaction is to add servers and resources, whereas an engineer's reaction should be to ask "why?".** Saying "it's slow" is not a diagnosis. -It's an admission that you've lost control of your system. +It's an admission of the loss of control over your system. ## A simple system is a mastered system -I'm not advocating for a lack of technology. +The most destructive phrase that now sets off alarm bells for me — one I encourage you to treat as a red flag whenever you hear it — is: "let's keep it simple!" + +Why? + +Because whoever says it often confuses "simple" with "simplistic." +In general, they're not from the field. + +To be clear: I'm not advocating for a lack of technology. A simple system is not a rudimentary system. It's a system where every element has a reason to exist. A mastered system is one where: -- you know why the CPU is saturated; -- you know why you need an additional network card; +- you know why the processor is saturated; +- you know why to add a network card; - you know why a faster disk is necessary; -- costs are genuinely understood, not just "10% less than last month." +- you understand the details of costs, not just "10% less than last month" at random. -This is the opposite of what I see in many companies. -Starting with cloud provider dashboards: meant to represent the state of the art, they are themselves frustratingly slow. +Does that seem obvious? Yet I see the opposite in many companies. +Starting with cloud provider interfaces. +They're supposed to represent the state of the art, yet they are frustratingly slow. -When the tools selling you performance are not themselves performant, that should be a signal. +When the providers selling you performance are not themselves performant, that should trigger a signal in our minds. ## The paradox of professionalism -In many organizations, complexity has become a marker of seriousness. +In many organizations, complexity has become a marker of seriousness. Does that resonate? I experienced this firsthand. My Unix architecture, my static files, my lightweight micro-services: all of it was perceived as tinkering. -While other event organizers struggled with their servers and CTFd, my system ran without a hitch. +While other event organizers struggled with their servers and the CTFd software, my system ran like clockwork. -Yet to the executive team, if some "engineer's tinkering" works for 10 years, it must not have been that complicated. +Yet from the outside, "engineer's tinkering" that works for 10 years can't have been that complicated! -On the other hand, a stack with Kubernetes, Kafka, and a service mesh will immediately be seen as "a real architecture." -Even if no one on the team truly understands it. +On the other hand, something built on Kubernetes, Kafka, and a service mesh will immediately be seen as "a real architecture." +Even if those who truly understand it are rare. **A simple system looks amateur. A complex system looks professional.** -This phenomenon has several roots. +In my opinion, this phenomenon has several roots. I've identified several, and there may be more. There is mimicry: copying Netflix and Google architectures without considering their constraints. It's the equivalent of building a three-Michelin-star restaurant kitchen to cook pasta. There is fear of blame: if the system breaks and you're using "industry standards," no one will be pointed at. -And there is the résumé effect: working with Kubernetes and Kafka boosts a career. Postgres and a monolith, much less so. +There is the résumé effect: working with Kubernetes and Kafka boosts a career. Postgres and a monolith, much less so. + +There is finally the abundance of cheap resources. +Why save on storage when disk prices keep falling? +Why save on RAM when adding more costs just a few dozen euros? +Why save on computing power when it's available on demand? +Yes, keeping things simple requires time from skilled people — who are rare and expensive resources. ## The *custom* doesn't disappear — it just moves -When my system was replaced by CTFd, in the name of standardization, the non-standard didn't disappear. -It just changed location. +When my successors replaced my system with the CTFd software in the name of standardization, the non-standard didn't disappear. +It changed location. -Sure, the core became a generic product, but everything around it — the orchestration, the scripts, the duct tape, the adaptations — became the new *custom*. +Sure, the core of the system became generic software. +But everything that completes it — the orchestration, the scripts, the duct tape, the adaptations — became the new *custom*. -And that code is often worse: less coherent, more scattered, less thoughtfully designed as a whole. +Guess what? That code is often worse: less coherent, more scattered, less thoughtfully designed as a whole. You replace a system conceived as a whole with an accumulation of workaround layers. -This is extremely common with modern architectures. +This example is common with modern architectures. You don't eliminate "complexity" — you move it to less visible, less controlled places. -Worse still, you have to keep up with the standard's evolution constantly: adapting your customizations, fighting structural changes, praying for [the goodwill of others](https://news.ycombinator.com/item?id=46136023). +Worse, you have to constantly keep up with the "standard" software's evolution: adapting your customizations, fighting structural changes, praying for [the goodwill of others](https://news.ycombinator.com/item?id=46136023). ## The cloud as a lazy solution -As a logical consequence, the cloud is today the primary lazy solution. -Not because it's useless — it has legitimate use cases — but because it allows you to mask problems instead of solving them. +As a logical consequence of this trend, the cloud is today the primary lazy solution. +Not because it's useless — it's legitimate for certain use cases — but because it allows you to mask problems instead of solving them. + +Faced with a technical problem, I see two paths. -Faced with a technical problem, there are two paths. The first: measure, understand, analyze. + The second: add resources, pile on abstractions, move the problem elsewhere. -Why has the second path become the norm? + +Why has this second path become the norm? **Adding machines is often easier than understanding a program.** -And that is where the real laziness lies. -Not in choosing simple hosting or a lightweight architecture. -But in refusing to understand what is actually happening inside the system. +It seems to me that the laziness lies here. +Not in choosing simple hosting or a lightweight architecture, but in the unwillingness to understand how the whole thing works and what is happening inside the system. ## Minimalism is not the absence of complexity -Some systems are extremely complex, and that's perfectly fine. -Google's search engine, Criteo's real-time ad auctions, ...: these are surgical systems where every component is justified, sometimes multiple times over. +Some systems are complex, and that's perfectly fine. +Google's search engine, Criteo's real-time ad auctions: these are surgical systems where every component is justified, sometimes multiple times over. That is exactly what minimalism in engineering means: keeping only the complexity that is indispensable. **Complexity is not a problem. Unnecessary complexity is.** -A startup with a few thousand users and a team of five developers does not face the same constraints as Netflix. +A company just starting out, with a few thousand users and a team of five developers, does not face the same constraints as Netflix. Yet many deploy the same architectures. ## AI makes this problem even more urgent -Today, AI tools can produce code and architectures at an unprecedented pace. +Today, artificial intelligence tools can produce code and architectures at an unprecedented pace. An entire system can be generated in a matter of hours. -This means **producing complexity has never been easier**. +As a result, **producing complexity has never been easier**. -In this context, the essential skill is shifting. -It is no longer just knowing how to code. -It is knowing how to contain the complexity that gets produced. -To remain in a reflective position rather than rushing headlong toward the first generated solution. +In this context, the skill is shifting. +It is no longer knowing how to code — it becomes knowing how to contain the complexity that gets produced. +It is about forcing yourself to think, rather than rushing headlong toward the first proposed solution. -AI is a formidable tool for quickly pivoting toward alternative solutions, for exploring different approaches. +Artificial intelligence is a formidable tool for quickly pivoting toward alternative solutions or for exploring different approaches. But you still need the perspective required to choose the right one. **Machines are learning to produce complexity. Engineers must learn to contain it.** -## The real role of the engineer +## The role of the engineer -An engineer is not a code producer. -Their role is to understand systems, master resources, and eliminate unnecessary complexity. +An engineer is not just a code producer. +Their role is to understand systems, master resources and costs, and eliminate unnecessary complexity. -A very good engineer often does *less*. -A well-designed system looks almost too simple. -And that is precisely why it goes unrecognized: **success erases the perception of difficulty.** +A good engineer often does *less*. +A well-designed system looks almost too simple, and that is often why it goes unrecognized: **success erases the perception of difficulty.** -When everything has been working for ten years, people end up thinking it couldn't have been that hard. - -As I sometimes hear: today, the rarest skill in software is not writing code. It's knowing when not to. +Today, the rarest skill in software is not writing code — it's knowing how to avoid writing it. ## Simplicity is a discipline -Simplicity is not an absence of technology. -It is the result of demanding engineering work. -It requires measurement, observation, and reflection. -It sometimes requires resisting the social pressure that pushes toward complexity. +I don't confuse simplicity with an absence of technology. +Let's say it is the result of demanding engineering work. +This demanding work requires measurement, observation, reflection, and sometimes resisting the social pressure that pushes toward complexity. -And in a world where machines can generate increasingly complex systems, the engineer's responsibility is to keep those systems understandable. +In a world where people and machines alike can generate complex systems, the engineer's responsibility is to keep those systems understandable. **Simplicity is not amateurism. It is what engineering produces when it matures.**