Références de bloc
Un énoncé, une adresse — single source of truth
Transcription
Et si une même définition ne se fragmentait pas en quatorze copies, mais vivait à une seule adresse — et que quatorze emplacements restaient synchronisés au lieu d'en oublier treize ? C'est exactement ce que font les références de bloc, et dans les minutes qui suivent vous entendrez comment elles fonctionnent et pourquoi elles réduisent la charge de maintenance à presque rien.
Un identifiant de bloc est un UUIDv4 — un emplacement canonique où un énoncé vit réellement. Avec des doubles parenthèses et l'identifiant entre elles, vous citez ce bloc partout, ((id)). Le bloc reste à son emplacement d'origine, et la citation affiche toujours l'état actuel. Modifiez la source, et quatorze citations suivent aussitôt.
La douleur sans références est silencieuse et coûteuse. Une définition migre par Ctrl+C dans quatorze pages. Six mois plus tard, quelque chose change, vous corrigez un emplacement et en oubliez treize. La cohérence entre définition et usage tombe sous la moitié sans que personne le remarque — jusqu'à ce que deux pages se contredisent et que les deux paraissent plausibles.
La différence entre référence et intégration compte. La référence ((id)) crée un lien — le lecteur saute par Ctrl+clic vers le bloc à son emplacement d'origine. L'intégration reflète le bloc en ligne, de sorte qu'il participe au flux de lecture. Règle empirique : ((id)) lorsque le lecteur doit sauter vers le contexte, l'intégration lorsque le bloc doit accompagner la lecture.
Le cas d'usage de référence naturel est l'Architecture Decision Record. Vous formulez une décision une seule fois, avec son propre identifiant. La roadmap, l'onboarding et le post-mortem la citent via ((id)). Quand la décision change, la correction à un seul endroit est visible dans chaque citation — pas de fork, pas de copie obsolète.
Voici la différence en chiffres. Avant : quatorze pages avec une définition copiée, treize d'entre elles silencieusement obsolètes, une charge de maintenance qui croît avec chaque usage. Après : un bloc, quatorze références, un seul emplacement à éditer, tout est synchronisé. La charge de maintenance reste constante, quel que soit le nombre de citations.
La question franche pour finir : à combien d'endroits « Client », « Lead » ou « Terminé » est-il défini dans votre wiki ? Si le nombre dépasse un, au moins l'un d'eux est obsolète. Un énoncé, une adresse — tout le reste n'est que miroir. Votre deuxième cerveau tient les fils ensemble et vous rend ce que vous lui confiez.
Les identifiants de bloc sont des UUIDv4. Une définition, une adresse. ((id)) la cite partout. La charge de maintenance lors d'une modification de définition baisse de 95 %, parce que vous éditez exactement un bloc et 14 emplacements restent synchronisés.
Le copier-coller entre les pages engendre de la dérive
Une définition migre par Ctrl+C dans 14 pages. Six mois plus tard, la définition change. Vous corrigez un emplacement, vous en oubliez 13. La cohérence entre définition et usage tombe sous les 50 %, sans que vous le remarquiez.
- Symptôme de dérive 1 : deux pages se contredisent, et les deux semblent plausibles.
- Symptôme de dérive 2 : la recherche de « ICP » renvoie 14 occurrences avec 4 définitions différentes.
- Symptôme de dérive 3 : personne ne sait quelle version fait foi — alors on en rédige une nouvelle. Et voilà la quinzième.
5 règles pour les références de bloc
- Un UUIDv4 par bloc. Chaque bloc reçoit un identifiant dès sa création, p. ex. 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12. Stable, sans collision, jamais à deviner.
- Référence de bloc ≠ intégration de bloc. ((id)) crée un lien — le bloc reste visible à son emplacement d'origine. {{embed ((id))}} reflète — le bloc apparaît en ligne à l'endroit de la citation.
- La syntaxe ((id)). Doubles parenthèses, l'UUID entre les deux, sans espace. L'autocomplétion se déclenche dès la saisie de ((.
- Source unique vs miroir. La définition vit à un seul endroit (la source). Tous les autres emplacements sont des miroirs via ((id)). Éditer le miroir = éditer la source.
- L'ADR comme cas d'usage de référence. Les Architecture Decision Records sont la source naturelle : formuler la décision une seule fois, puis la référencer dans la roadmap, l'onboarding, le post-mortem via ((id)).
## ADR-007: Block-IDs sind UUIDv4
id:: 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12
Wir verwenden UUIDv4 für Block-IDs, weil:
- kollisionsfrei ohne zentrale Vergabe
- 122 Bit Entropie reichen für 10^36 Blöcke
- offline generierbar (crypto.randomUUID())
---
## Roadmap Q3
Siehe Entscheidung: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))
## Onboarding für neue Devs
ID-Schema: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))Avant/après — 14 clones Wikipédia vs un seul bloc, intégré 14 fois
| Avant | Après |
|---|---|
| 14 pages avec la définition d'ICP copiée | 1 bloc, 14 références via ((id)) |
| Édition à 14 emplacements, 13 oubliés | Édition à 1 emplacement, 14 emplacements synchronisés |
| Recherche « ICP » → 14 occurrences, 4 versions | Recherche « ICP » → 1 source, 14 rétroliens |
| Dérive inaperçue, contradictions dans le wiki | Dérive structurellement exclue |
| La charge de maintenance croît avec les usages | Charge de maintenance constante, quel que soit le nombre d'usages |
<!-- Source-Block (lebt in /glossar/icp.md) -->
id:: a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50
ICP (Ideal Customer Profile): Beschreibung des Konto-Typs, der mium am stärksten profitiert — Branche, Größe, Wissensvolumen, Compliance-Frame.
<!-- Verwendung in /sales/playbook.md -->
Unser ICP: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /onboarding/woche-1.md -->
Lies zuerst: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /roadmap/2026.md -->
Fokus 2026: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))Question franche
Combien de fois avez-vous dû maintenir la même définition à des emplacements différents ? Comptez les endroits où « Client », « Lead » ou « Terminé » est défini dans votre wiki. Si le nombre dépasse 1, au moins l'un d'eux est déjà obsolète.
Un énoncé, une adresse. Tout le reste n'est que miroir.
Un énoncé. Une adresse.
Bâtissez votre connaissance pour qu'une modification se propage partout — votre deuxième cerveau tient les fils ensemble.
Réserver mon créneau··gratuit →