Documentatie Visie
Laatst bijgewerkt: 2026-05-19 Status: Actief
Waarom dit document bestaat
Per-app documentatie staat in de product-repos (Databank, Geoportaal, Projectbeheer, Workspace, Opdrachten-Scanner, …). Bureauprocessen staan in Ruimtemeesters Processen. De cross-repo vragen — hoe verhouden deze apps zich, waar vind ik X, wat is het contract tussen Y en Z, waar gaat het portfolio naartoe — hadden geen thuis. Nieuwe collega's en het toekomstige-ik moesten elke repo afzonderlijk doorkruipen om een portfoliobeeld op te bouwen.
Dit document verankert waarvoor Ruimtemeesters Documentatie bestaat, wat het bezit en wat het bewust niet doet.
Wat Documentatie is
Een cross-repo navigatielaag voor het Ruimtemeesters-portfolio. Het vervangt geen enkele product-repo zijn eigen docs; het maakt ze samen leesbaar.
De kerngebruiker
Toekomstig-ik en nieuwe collega's — ontwikkelaars die de codebase-stijl al snappen maar hun weg moeten vinden door veel repos heen. Secundair: iedereen die moet besluiten waar nieuwe docs horen.
Pijnpunten die deze visie adresseert
- Weten welke repo een vraag oplevert vereist nu eerst meerdere repos openen.
- Cross-repo contracten (HTTP, MCP, gedeelde schema's) zijn impliciet in code en staan nergens opgeschreven waar een lezer ze vindt.
- Het overzicht "wat is deze app en hoe verhoudt-ie zich tot de rest" leeft alleen in het hoofd.
- Gebruikershandleidingen voor end-to-end workflows die meerdere apps raken hebben geen huisvesting.
Drie taken
| Taak | Wat het oplevert | Modus | Map |
|---|---|---|---|
| Atlas | Portfolio-kaart, woordenlijst, "waar staat X", hoe de apps zich verhouden | Eigen inhoud, hier geschreven | 60-portfolio-atlas/ |
| Referentie | API-docs-stijl materiaal: HTTP-endpoints, MCP-tools, gedeelde schema's, app-naar-app contracten | Gegenereerd uit product-repos waar mogelijk | 70-api-referentie/ |
| Handleiding | Taakgerichte handleidingen voor het end-to-end bedienen van de apps | Eigen inhoud, hier geschreven | 80-handleidingen/ |
De geërfde mappen (00-visie/ t/m 50-implementatieplannen/) bevatten cross-cutting overlay-inhoud. Per-app planning-artefacten blijven thuis in de product-repo; in deze repo staan de één-pagina overlays die ze verbinden.
Overlay, geen mirror
De keten visie/onderzoek/PRD/ADR/TDS/plan blijft in elke product-repo. Documentatie bevat overlay-documenten — één cross-cutting pagina per laag die wijst naar en context geeft bij de per-repo originelen.
Voorbeeld: een toekomstige 00-visie/portfolio-visie.md beschrijft hoe Databank, Geoportaal, Opdrachten-Scanner, … zich verhouden als portfolio, en linkt naar elke repo zijn eigen visie als bron van waarheid.
Het besluit staat in [[PORTFOLIO-001-overlay-geen-mirror]].
Gegenereerd waar mogelijk
Met-de-hand-bijgehouden mirrors verouderen binnen weken. De overlay-pagina's en de API-referentie zijn bedoeld om gegenereerd te worden uit zusterrepos (READMEs, visie-docs, OpenAPI-specs, MCP-tool registries), met handgeschreven narrative er bovenop. De generator leeft in deze repo; de bron van waarheid blijft waar de code staat.
De komende 6–12 maanden
- Een werkende portfolio-atlas die elke huidige app dekt
- Gegenereerde API-referentie voor minstens Databank en Geoportaal
- Handleidingen voor de twee meestgebruikte end-to-end workflows (BOPA-toetsing, raadsinformatie-ingestie)
- Overlay visie-pagina (één alinea per app, met links naar de originelen)
- Generator die zusterrepos uitleest en de overlay + referentie-pagina's emit
- ADRs die de cross-repo besluiten vastleggen die nu impliciet zijn
Niet-doelen
- Documentatie bezit geen per-app visie, PRDs, ADRs, TDSs of implementatieplannen. Die blijven in de product-repo.
- Documentatie volgt geen werk-in-uitvoering, sprints of backlog. Daarvoor zijn GitHub Issues, geen bestanden.
- Documentatie dupliceert geen inhoud uit Ruimtemeesters Processen. Processen bezit hoe het bureau werkt; Documentatie bezit hoe de apps samen het portfolio vormen.
- Documentatie wordt niet het primaire leesthuis voor één enkele app. De product-repo blijft daarvoor gezaghebbend.
Gerelateerd
- [[PORTFOLIO-001-overlay-geen-mirror]] — het besluit om te overlayen in plaats van te dupliceren