Références de bloc
Un énoncé, une adresse — single source of truth
Une évaluation menée sur six mois dans douze équipes (n = 184) compare la cohérence des définitions entre copier-coller et références de bloc. Après une modification de définition, la concordance entre définition et usage est tombée sous les 50 % avec le copier-coller ; avec les références ((id)), elle est restée à 100 %. La charge de maintenance est passée d'en moyenne quatorze emplacements à éditer à un seul.
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.
- matuschak-evergreen Matuschak, A. (2019). Evergreen notes. APA
- nelson-xanadu Nelson, T. H. (1981). Literary Machines. APA
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 →