PORTFOLIO-001: Documentatie gebruikt een overlay-model, geen mirror
Status: Geaccepteerd Datum: 2026-05-19
Context
Ruimtemeesters Documentatie is de cross-repo navigatielaag voor het product-portfolio. Om die rol te vervullen moet hij verwijzen naar inhoud (visies, PRDs, ADRs, TDSs, plannen) die in andere repos staat.
Drie plausibele modellen:
- Mirror — kopieer de per-repo docs op schrijftijd naar Documentatie en houd ze gesynchroniseerd.
- Overlay — houd per-repo docs als bron van waarheid; hier komen korte cross-cutting pagina's die naar de originelen linken.
- Centraliseren — verplaats alle planning-docs naar Documentatie; product-repos houden alleen code.
Mirroren vraagt om synchronisatiediscipline die in dit soort opzetten in de praktijk altijd verslapt; kopieën lopen binnen weken na schrijven uit elkaar met hun origineel.
Centraliseren scheidt docs van de code die ze beschrijven. Een TDS voor het datamodel van Databank hoort bij de code die hij beperkt, niet in een parallelle repo die een reviewer apart moet onthouden.
De doelgroep is "toekomstig-ik en nieuwe collega's" — vindbaarheid over het portfolio heen weegt zwaarder dan volledigheid van één pagina in deze repo.
Besluit
Documentatie gebruikt het overlay-model.
- Per-app visie/onderzoek/PRD/ADR/TDS/plan-documenten leven in elke product-repo en blijven daar.
- Documentatie bevat per laag één cross-cutting overlay-pagina (bijv. een toekomstige
00-visie/portfolio-visie.md) die naar de per-repo originelen linkt. - Overlay-pagina's en de API-referentie worden gegenereerd uit zusterrepos waar mogelijk, met handgeschreven narrative er bovenop.
Gevolgen
Wat de standaard wordt
- Per-app planning-artefacten blijven in de product-repo. Alleen cross-cutting inhoud wordt hier geschreven.
- Overlay-pagina's linken altijd naar de per-repo bron; ze parafraseren niet wat het origineel al goed zegt.
- Generatietooling leest zusterrepos op build-tijd; we committen geen kopieën van hun bestanden.
Wat expliciet niet de standaard is
- Bulksgewijs kopiëren van per-repo docs naar Documentatie.
- Documentatie als de enige plek die iemand hoeft te lezen om één app te begrijpen.
- Een "Documentatie zegt X, product-repo zegt Y"-divergentie — als die conflicteren wint de product-repo per definitie.
Geaccepteerde trade-offs
- Lezers moeten soms een link volgen om bij de volledige inhoud te komen. Acceptabel: de doelgroep is comfortabel met navigeren tussen repos; het alternatief (verouderde mirrors) is slechter.
- Generatietooling voegt een onderhoudsdimensie toe. Acceptabel: simpeler dan handgeschreven mirrors, en een falende generator is luid (gebroken build) terwijl een verouderde mirror stil rot.
- De waarde van Documentatie is deels latent totdat de generator bestaat. Acceptabel: atlas-pagina's (
60-portfolio-atlas/) en handleidingen (80-handleidingen/) leveren losstaande waarde terwijl de generator wordt gebouwd.
Overwogen alternatieven
Mirror. Kopieer de per-repo docs op schrijftijd met een header die de bron noemt. Afgewezen omdat synchronisatiediscipline in de praktijk altijd faalt; twee kopieën van dezelfde inhoud garanderen divergentie, en het stille faalpatroon is erger dan geen doc.
Centraliseren. Verplaats alle planning-docs hierheen. Afgewezen omdat het docs van de code waaraan ze toebehoren scheidt, het principe breekt dat per-repo docs bij per-repo code horen, en een permanente "welke repo moet deze PR aanraken?"-wrijving creëert voor elke verandering.