Documentatie docs
De nummering volgt een piramide van intentie naar uitvoering, plus drie afsluitende mappen voor de eigen inhoud die alleen in deze repo bestaat (atlas, referentie, handleidingen). Gaten van 10 laten ruimte voor nieuwe categorieën zonder hernummeren.
00-visie/ Waarvoor deze repo bestaat; portfolio-brede visie-overlays
05-user-journeys/ Cross-app user journeys
10-architectuur/ Hoe de apps in elkaar grijpen (levend)
15-use-cases/ Canonieke cross-app scenario's
20-adr/ Cross-repo architectuurbesluiten (onveranderlijk)
25-onderzoek/ Verkennende notities over cross-repo onderwerpen
30-prd/ Product-vereisten die repo-grenzen overschrijden
40-tds/ Technisch ontwerp voor cross-repo werk
50-implementatieplannen/ Plannen voor cross-repo initiatieven (kortlevend)
60-portfolio-atlas/ Portfolio-kaart, woordenlijst, "waar staat X" (eigen)
70-api-referentie/ API-contracten — gegenereerd waar mogelijk
80-handleidingen/ Taakgerichte gidsen voor end-to-end workflows (eigen)
Twee modi
Documentatie heeft twee duidelijk verschillende soorten inhoud. Ze leven in dezelfde docs/-boom maar volgen verschillende regels.
Overlay-modus (00/ t/m 50/). Cross-cutting samenvattingen die linken naar per-repo originelen. Per-app planning-artefacten blijven in de product-repo; hier staat de pagina die ze aan elkaar knoopt. Besluit: [[PORTFOLIO-001-overlay-geen-mirror]].
Eigen-modus (60/ t/m 80/). Atlas-pagina's, API-referentie en handleidingen bestaan in geen enkele product-repo. Ze worden hier geschreven (of gegenereerd) en zijn het canonieke thuis van hun inhoud.
Hoe artefacten doorstromen
visie ──────────────────────────► PRD ──► TDS ──► plan ──► opgeleverd
│ │
journeys + use cases ── context ──┤ │
└─► ADR ◄─┘ (besluiten waar beide naar verwijzen)
10-architectuur/ is een levende momentopname die meebeweegt zodra PRDs/TDSs landen.
60-atlas/ + 70-referentie/ + 80-handleidingen/ staan op zichzelf en reflecteren de
huidige staat van het portfolio.
Een cross-cutting initiatief (bijv. een nieuw gedeeld schema, een nieuw app-naar-app contract) levert, in volgorde, op:
- PRD onder
30-prd/— wat de gebruiker zichtbaar moet merken - ADR(s) onder
20-adr/— voor elk besluit dat alternatieven afsluit - TDS onder
40-tds/— het technische doel - Implementatieplan onder
50-implementatieplannen/— stap-voor-stap uitvoering - Updates op atlas / referentie / handleidingen zodra het werk landt
Per-app planning blijft in de product-repo gebeuren — daarvoor komen hier geen bestanden bij.
Wat hier niet thuishoort
- Per-app planning-artefacten — die staan in de product-repo (Databank, Geoportaal, …)
- Backlog en bugs — GitHub Issues
- Lopende takenlijsten — GitHub Issues of een sprintbord, geen bestanden
- Statusupdates en notulen — chat of e-mail, niet de repo
- Bureaubrede procesinhoud — dat is Ruimtemeesters Processen
Twijfel je of iets hier hoort? Vraag: is dit alleen logisch over meerdere repos heen? Zo nee, dan hoort het waarschijnlijk in de docs/ van één enkele repo.
Naamgevingsconventies
| Map | Bestandspatroon | Voorbeeld |
|---|---|---|
00-visie/ | <onderwerp>-visie.md | documentatie-visie.md |
05-user-journeys/ | <persona>-<journey>-journey.md | ontwikkelaar-bopa-toetsing-cross-app-journey.md |
10-architectuur/ | <gebied>-architectuur.md | portfolio-architectuur.md |
15-use-cases/ | <actor>-<actie>-use-case.md | databank-publiceert-naar-geoportaal-use-case.md |
20-adr/ | <GEBIED>-<NNN>-<slug>.md | PORTFOLIO-001-overlay-geen-mirror.md |
25-onderzoek/ | <onderwerp>.md | mcp-tool-registry-generatie.md |
30-prd/ | <slug>-prd.md | cross-repo-woordenlijst-prd.md |
40-tds/ | TDS-<GEBIED>-<NNN>-<slug>.md | TDS-PORTFOLIO-001-overlay-generator.md |
50-implementatieplannen/ | <slug>-plan.md | overlay-generator-plan.md |
60-portfolio-atlas/ | <onderwerp>-atlas.md of vast (portfolio-map.md, woordenlijst.md) | portfolio-map.md |
70-api-referentie/ | <app>-<surface>-referentie.md | databank-http-referentie.md |
80-handleidingen/ | <app>-<taak>-handleiding.md of <taak>-handleiding.md voor cross-app | bopa-toetsing-end-to-end-handleiding.md |
Elke map heeft een eigen README.md met conventies, statuswaarden en een sjabloon om uit te kopiëren.