Ton articles de blog

Le piege classique

Un article qui suit le plan du cours/projet/outil au lieu de suivre l’arc de l’experience. Symptomes : - La structure ressemble a une table des matieres (section 1 = chapitre 1, section 2 = chapitre 2…) - Les “ce que j’ai applique” sont colles mecaniquement apres chaque notion - Le texte pourrait etre ecrit par quelqu’un qui n’a pas fait le projet - Trop de diagrammes qui repetent ce que le texte dit deja

Principes

  • Le fil narratif suit l’experience, pas la source : partir du probleme concret, pas du plan du cours ou de la doc
  • Un seul fil rouge : un projet, un probleme, une progression. Pas un catalogue de notions
  • Les concepts arrivent quand ils resolvent quelque chose : on introduit ReAct quand on explique pourquoi l’agent etait nul, pas parce que c’est le chapitre 3
  • Montrer les declics : le moment ou tu comprends pourquoi ca marchait pas. “J’ai passe 45 minutes a debugger un tool” > “Le cours explique que les docstrings sont importantes”
  • Les diagrammes appuient le propos, ils ne le remplacent pas : si le texte dit deja la meme chose, le diagramme est en trop. Garder 2-3 max.
  • Pas de tableaux artificiels : un tableau avant/apres ou une comparaison de modeles, ca sent la slide de presentation. Integrer l’info dans le texte.
  • Les sections secondaires sont condensees : si un sujet n’est pas central a l’experience, il va dans un “en vrac” ou une liste, pas dans un H2 avec sous-sections
  • Honnete sur les galeres : les vrais pieges, pas les difficultes generiques. “Le rate limiting echoue silencieusement” > “il y a des challenges”

Structure type

  1. Le probleme concret : qu’est-ce qui marchait pas, pourquoi c’etait frustrant
  2. Le declic : qu’est-ce qui a change la comprehension
  3. Ce qui a concretement change : pas “j’ai appris X”, mais “j’ai change Y dans mon projet et voila le resultat”
  4. Les pieges : ce que personne ne mentionne, les vrais bugs, le temps perdu
  5. Le bilan : court, factuel, pas de grandes lecons de vie

A eviter

  • Structure calquee sur le plan du cours/outil/formation
  • “Ce que le cours m’a fait comprendre” (mecanique)
  • Diagrammes qui paraphrasent le texte
  • Tableaux comparatifs forces (avant/apres, modele A vs B)
  • Sections H2 pour des sujets peripheriques
  • Conclusions avec des platitudes (“c’est un bon investissement”, “formation faite par passion”)
  • Ton catalogue : lister des features sans les relier a un probleme concret

Test simple

Si tu peux intervertir deux sections sans que ca change rien, c’est un catalogue, pas un recit.

Exception : articles de reference / base de connaissance

Certains articles ont un objectif different : servir de reference consultable et de checklist operationnelle, pas de raconter une experience. Ce format est legitime et assume — mais il a ses propres regles.

Quand c’est legitime

  • L’objectif explicite est d’avoir un document de reference reutilisable (checklist, synthese de framework, aide-memoire)
  • Le lecteur cible est “soi dans 6 mois” ou un collegue qui veut un point d’entree structure
  • La formation/source couvre un domaine large sans fil narratif naturel (ex : gouvernance, compliance, securite)

Ce qui change

  • La structure peut suivre les domaines, pas l’experience — c’est le but, pas un piège
  • Les diagrammes sont plus nombreux (jusqu’a 8-10) car ils servent de reference visuelle rapide, pas d’illustration d’un propos
  • Les tableaux sont autorises quand ils servent la consultation (matrice de risques, liste de politiques avec colonnes) — pas quand ils remplacent une analyse
  • La checklist est un livrable en soi, pas une conclusion decorative

Ce qui ne change pas

  • Honnete sur les limites : ce que la source ne couvre pas, ce qu’il faut completer ailleurs
  • Pas de platitudes en conclusion
  • Ancrage dans le probleme reel : pourquoi tu en as eu besoin, dans quel contexte tu vas t’en servir — meme court, meme en intro
  • Pas de liste de features sans contexte : chaque element de checklist doit avoir une raison d’etre implicite ou explicite

Test simple pour ce format

Si tu retires la checklist et les diagrammes, est-ce qu’il reste quelque chose que quelqu’un d’autre ne pourrait pas ecrire sans avoir fait la formation ? Si non, ajouter le “pourquoi ca m’a servi” et “ce que ca change concretement”.

Positionnement “sachant” — cibler les points douloureux entreprise

Certains articles ont pour cible un lecteur professionnel (DSI, RSSI, architecte, DPO) qui a deja des problemes concrets. L’objectif n’est plus “voici ce que j’ai appris” — c’est “voici ce qui manque dans votre organisation, et comment le resoudre”.

Principe de base

Le positionnement en tant que sachant doit etre implicite dans la structure, pas proclame. Le lecteur comprend que tu sais de quoi tu parles parce que tu nommes ses problemes avec precision — pas parce que tu listes tes annees d’experience.

Ce qui change par rapport au ton REX standard

  • L’intro part du probleme du lecteur, pas du tien. Pas “j’ai suivi cette formation”, mais “voici ce qui manque dans la plupart des deploiements GenAI”.
  • Les callouts warning adressent des pieges que le lecteur a probablement deja eus — nommer le scenario exact (“les dumps de backup en clair sur S3”) cree la reconnaissance et la credibilite.
  • La conclusion ouvre vers un contact / une mission sans le formuler crument. “Si vous voulez discuter de l’application de ce cadre a votre contexte” > “n’hesitez pas a me contacter”.
  • Une phrase de contexte terrain suffit pour le positionnement explicite — pas de liste de missions, pas de CV inline. Ex : “Sur plusieurs missions d’infrastructure et MLOps, j’ai vu le meme scenario se repeter”.

Points douloureux a adresser selon la cible

DSI / RSSI : - Pas de politique de donnees formalisee (risque juridique si audit ou breach) - Deploiement GenAI sans audit de risques (angle mort jusqu’a l’incident) - Vendors IA sans due diligence (conformite GDPR du provider non verifiee) - Logs et donnees PII mal proteges (oublies dans le perimetre de securite) - Pas de plan de reponse aux incidents teste (existe sur papier, jamais simule)

Architecte / Tech Lead : - Absence de data masking en environnements non-prod - RBAC configure au lancement, jamais revise - Chiffrement en base mais backups en clair - Qualite des donnees d’entree non validee (garbage in, garbage out en RAG)

DPO / Manager : - Classification des donnees inexistante ou trop grossiere - Retention des logs de conversation non definie - Droits des personnes concernees non appliques aux donnees qui transitent dans le LLM

Structure type pour ce format

  1. Intro courte : le scenario que le lecteur reconnait (1 phrase de contexte terrain + le probleme recurrent)
  2. Les angles morts : nommer les 3-5 problemes concrets, en callout warning — pas en liste generique
  3. Le cadre : la structure de solution, avec diagrammes pour la lisibilite
  4. Les details operationnels : ce qui compte vraiment, avec les pieges specifiques (pas les difficultes generiques)
  5. La checklist : livrable actionnable, directement utilisable
  6. Ce que ca ne remplace pas : honnetetee sur les limites + ouverture vers l’echange

A eviter dans ce format

  • Titre du type “Ce que j’ai appris en suivant X” — cible le mauvais lecteur
  • Intro qui parle de soi avant de parler du probleme du lecteur
  • Pieges generiques (“il y a des defis”) au lieu de scenarios precis
  • Conclusion sans ouverture vers un echange ou une prochaine etape

Quarto — regles specifiques

L’outil de publication est Quarto. Ce qui change dans la production :

Diagrammes

  • Utiliser Mermaid natif dans les blocs ```{mermaid} — pas de diagrammes en image externe
  • Chaque diagramme doit apporter quelque chose que le texte ne dit pas deja
  • Pour les articles de reference : flowchart (processus), quadrantChart (matrices de risques), sequence (interactions)
  • Zoom click-to-fullscreen : tout article contenant des diagrammes Mermaid doit inclure le bloc CSS/JS de zoom dans le frontmatter (include-in-header pour le CSS .mermaid-wrapper / .mermaid-wrapper.zoomed, include-after-body pour le JS). Voir posts/genai-governance/index.qmd pour le code de reference.

Mise en forme enrichie

  • Callouts pour les points critiques et les pieges :
    • {.callout-warning} — pieges, points de vigilance
    • {.callout-tip} — bonnes pratiques
    • {.callout-important} — elements non negociables
    • {.callout-note collapse="true"} — details optionnels repliables
  • Tabsets {.panel-tabset} pour comparer des alternatives (frameworks, approches) sans allonger la page
  • Checkboxes - [ ] pour les checklists operationnelles — cochables dans le navigateur en session

Front matter minimal

---
title: "..."
date: "YYYY-MM-DD"
categories: [tag1, tag2]
author: "Sylvain Pham"
format:
  html:
    toc: true
    toc-depth: 3
    toc-location: left
    number-sections: true
    smooth-scroll: true
    anchor-sections: true
---

Langue

  • Toujours écrire les articles avec les accents français (é, è, ê, à, ù, ç, etc.). Les articles sont publiés et lus, pas des fichiers de config.
  • Ce fichier (blog-tone.md) est volontairement sans accents, mais les articles .qmd doivent être accentués correctement.

A eviter en Quarto

  • Callouts en cascade (max 2-3 par section, sinon ca noie l’essentiel)
  • Tabsets pour du contenu qui se lit mieux en sequence
  • number-sections: true sur les articles narratifs (ca casse le ton)