8. Deel, hergebruik en werk samen
Door samen te werken, kennis te delen en oplossingen te hergebruiken, kunnen overheidsorganisaties efficiënter werken, kosten besparen en betere diensten leveren aan burgers en bedrijven.
Waarom is het belangrijk?
- Interoperabiliteit: Systemen kunnen gemakkelijk gegevens uitwisselen en samenwerken
- Kosteneffectiviteit: Voorkom dat het wiel meerdere keren wordt uitgevonden
- Hogere kwaliteit: Profiteer van bestaande, bewezen oplossingen
- Snellere implementatie: Versnel projecten door bestaande componenten te gebruiken
- Kennisdeling: Leer van ervaringen en expertise van anderen
- Standaardisatie: Bevorder consistentie en interoperabiliteit
- Innovatie: Combineer inzichten en benaderingen voor nieuwe oplossingen
Door actief samen te werken, kennis te delen en bestaande oplossingen te hergebruiken, kan de overheid efficiënter werken, kosten besparen en consistentere diensten leveren aan burgers en bedrijven.
Hoe pas je het toe?
Direct aan de slag
Samenwerking bevorderen
- Maak het vindbaar: Zorg dat gedeelde bronnen gemakkelijk te vinden zijn
- Documenteer goed: Maak duidelijk hoe iets kan worden hergebruikt
- Bouw gemeenschappen: Creëer platforms voor samenwerking
- Stimuleer hergebruik: Maak het aantrekkelijker om te hergebruiken dan opnieuw te bouwen
- Vier successen: Deel voorbeelden van succesvolle samenwerking
- Betrek belanghebbenden: Includeer diverse perspectieven
- Creëer een cultuur van delen: Maak samenwerking onderdeel van de organisatiecultuur
Wat kan worden gedeeld en hergebruikt
- Broncode: Open source software specifiek voor de overheid (zie Werk transparant en gebruik open source)
- Componenten: Herbruikbare technische bouwstenen
- Architectuurpatronen: Beproefde ontwerpmodellen
- API's: Interfaces voor gegevensuitwisseling (zie Integreer en pas technologie aan)
- Datasets: Gegevens die nuttig zijn voor meerdere organisaties (zie Maak beter gebruik van data)
- Contracten en aanbestedingen: Sjablonen en frameworks (zie Definieer je inkoopstrategie)
- Kennis en documentatie: Best practices, handleidingen en richtlijnen
- Methodologieën: Processen en werkwijzen
Uitdagingen en oplossingen
- Niet-hier-uitgevonden syndroom: Promoot de voordelen van hergebruik
- Governance: Ontwikkel duidelijke verantwoordelijkheden voor gedeelde bronnen
- Verschillende prioriteiten: Vind gemeenschappelijke doelen
- Interoperabiliteit: Gebruik open standaarden om compatibiliteit te verzekeren
- Juridische barrières: Ontwikkel passende licenties en overeenkomsten
- Organisatorische grenzen: Creëer overkoepelende samenwerkingsstructuren
Samenwerkingsplatforms en hulpmiddelen
- Gemeenschappelijke coderepositorys
- Kennisbanken en wiki's
- Communities of practice
- Samenwerkingssessies en hackathons
- Overkoepelende projectteams
- Gedeelde databases en dataplatforms
Voorbeelden van herbruikbare componenten
- Authenticatiemechanismen
- Betalingssystemen
- Formulieroplossingen
- Notificatieservices
- Gegevensbeheertools
- Documentbeheersystemen
Documenteer je project effectief
Goede documentatie is essentieel voor het succesvol ontwikkelen, onderhouden en overdragen van digitale systemen. Dit principe richt zich op het kiezen van de juiste documentatietools en -aanpak voor overheidsprojecten.
Direct aan de slag
MkDocs Material Template
Start met een voorgeconfigureerde MkDocs setup
Template downloadenWaarom dit belangrijk is
- Kennisoverdracht: Documentatie zorgt ervoor dat kennis behouden blijft wanneer teamleden wisselen
- Onderhoud: Goed gedocumenteerde systemen zijn eenvoudiger te onderhouden en uit te breiden
- Transparantie: Openbare documentatie draagt bij aan transparantie van overheidshandelen
- Samenwerking: Heldere documentatie vergemakkelijkt samenwerking tussen teams en organisaties
- Compliance: Veel overheidsprojecten hebben documentatievereisten voor audit en compliance
Documentatietools vergelijking
Material for MkDocs (Aanbevolen)
Voordelen:
- Uitstekende zoekfunctionaliteit met previews
- Moderne, responsive interface
- Ondersteuning voor diagrammen (Mermaid)
- Grote community en actieve ontwikkeling
- Statische site generatie (veilig en snel)
- Markdown-gebaseerd (toegankelijk voor ontwikkelaars)
Nadelen:
- Beperkte out-of-the-box functionaliteit voor gestructureerde besluitvorming (ADRs)
Gebruikt door: AI Validatie team, Algoritmekader, FastAPI, Ruff
Docusaurus
Voordelen:
- React-gebaseerd met moderne interface
- Goede ondersteuning voor versioning
- Uitbreidbaar met plugins
- Grote community (Facebook/Meta)
Nadelen:
- Zoekfunctionaliteit vaak afhankelijk van externe diensten (Algolia)
- Complexer dan MkDocs voor eenvoudige documentatie
Gebruikt door: developer.overheid.nl
Structurizr
Voordelen:
- Specifiek ontworpen voor software architectuur documentatie
- Ondersteuning voor Architecture Decision Records (ADRs)
- C4 model integratie
Nadelen:
- Minder soepele zoekfunctionaliteit
- Beperktere community
- Focus op architectuurdocumentatie kan beperkend zijn
Gebruikt door: MijnOverheid Zakelijk
Sphinx
Voordelen:
- Uitgebreide functionaliteit
- Sterke ondersteuning voor technische documentatie
- Automatische API documentatie generatie
Nadelen:
- Steilere leercurve
- Complexere configuratie
- reStructuredText i.p.v. Markdown (minder toegankelijk)
Gebruikt door: OpenKat (VWS)
ReSpec
Voordelen:
- Specifiek voor technische standaarden
- W3C standaard
- Goede ondersteuning voor referenties en citaties
Nadelen:
- Geen ingebouwde zoekfunctionaliteit
- Beperkte community buiten standaardisatieorganisaties
- Minder geschikt voor algemene projectdocumentatie
Gebruikt door: standaarden beheerders (Logius, Geonovum, etc...)
Gebaande paden: Material for MkDocs
Voor de meeste overheidsprojecten bevelen we Material for MkDocs aan als de voorkeursoplossing voor projectdocumentatie.
Waarom Material for MkDocs?
- Gebruiksgemak: Markdown is toegankelijk voor zowel technische als niet-technische teamleden
- Zoekfunctionaliteit: Ingebouwde, snelle zoekfunctionaliteit zonder externe afhankelijkheden
- Statische generatie: Veilig, snel en eenvoudig te hosten
- Proven track record: Succesvol gebruikt in vergelijkbare overheidsprojecten
- Community: Grote, actieve community en goede documentatie
- Uitbreidbaarheid: Plugins voor diagrammen, tabellen, en meer
Basissetup
Een standaard MkDocs configuratie voor overheidsprojecten:
site_name: Project Naam
site_description: Korte beschrijving van het project
site_url: https://jouw-organisatie.github.io/project-naam
theme:
name: material
palette:
- scheme: default
toggle:
icon: material/weather-sunny
name: Schakel naar donkere modus
- scheme: slate
toggle:
icon: material/weather-night
name: Schakel naar lichte modus
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.path
- search.highlight
- search.share
- content.code.copy
plugins:
- search:
lang: nl
- mermaid2
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- admonition
- pymdownx.details
- attr_list
- md_in_html
nav:
- Home: index.md
- Architectuur: architecture/
- Ontwikkeling: development/
- Deployment: deployment/
- ADRs: decisions/
Documentatiestructuur
Aanbevolen mappenstructuur:
docs/
├── index.md # Project overzicht
├── architecture/ # Architectuurdocumentatie
│ ├── overview.md
│ ├── components.md
│ └── deployment.md
├── development/ # Ontwikkelaardocumentatie
│ ├── setup.md
│ ├── guidelines.md
│ └── testing.md
├── decisions/ # Architecture Decision Records
│ ├── 001-framework-choice.md
│ └── template.md
└── deployment/ # Implementatiedocumentatie
├── environments.md
└── procedures.md
Implementatie tips
- Start eenvoudig
Begin met een basisstructuur en bouw uit naarmate het project groeit.
- Gebruik templates
Creëer templates voor veelvoorkomende documenttypen zoals ADRs, API documentatie, en runbooks.
-
Automatiseer waar mogelijk
-
Automatische generatie van API documentatie
- Regelmatige builds bij code wijzigingen
-
Link checking voor broken links
-
Betrek het team
-
Maak documentatie onderdeel van de Definition of Done
- Organiseer documentatie reviews
-
Train teamleden in Markdown en MkDocs
-
Houd het actueel
-
Koppel documentatie updates aan code wijzigingen
- Implementeer documentatie als code
- Plan regelmatige documentatie reviews
Architecture Decision Records (ADRs)
Voor het vastleggen van belangrijke beslissingen bevelen we Architecture Decision Records aan. Deze kunnen eenvoudig worden geïntegreerd in MkDocs:
ADR Template
# ADR-001: [Titel van de beslissing]
## Status
[Voorgesteld | Geaccepteerd | Vervangen | Verouderd]
## Context
Beschrijf de situatie en het probleem dat een beslissing vereist.
## Beslissing
Beschrijf de gekozen oplossing en waarom deze is gekozen.
## Gevolgen
Beschrijf de gevolgen van deze beslissing, zowel positief als negatief.
## Alternatieven overwogen
Beschrijf welke andere opties zijn overwogen en waarom deze niet zijn gekozen.
Ondersteuning en resources
- MkDocs documentatie: https://www.mkdocs.org/
- Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
- Markdown guide: https://www.markdownguide.org/
- Mermaid diagrammen: https://mermaid-js.github.io/mermaid/
Door deze aanpak te volgen, creëer je documentatie die niet alleen nuttig is voor je huidige team, maar ook waarde biedt voor toekomstige ontwikkelaars en stakeholders.
UK Government Digital Service: Ervaringen van de Britse overheid
De UK Government Digital Service (GDS) is het digitale centrum van de Britse overheid, verantwoordelijk voor het vaststellen, leiden en leveren van de visie voor een moderne digitale overheid. GDS heeft sinds 2011 baanbrekend werk verricht in digitale transformatie en heeft uitgebreide bronnen en richtlijnen ontwikkeld voor het verminderen van risico's bij digitale overheidsprojecten.
Belangrijkste concepten
-
Digital by Default strategie
- Gebruikersbehoeften centraal stellen bij serviceontwerp
- Digitale services die zo goed zijn dat mensen ze verkiezen boven niet-digitale alternatieven
- Iteratieve ontwikkeling gebaseerd op gebruikersonderzoek en feedback
-
GOV.UK Design System
- Herbruikbare componenten en patronen voor consistente gebruikerservaringen
- Bewezen toegankelijke en gebruiksvriendelijke ontwerpelementen
- Uitgebreide documentatie voor implementatie
-
Moderne procurement en leveranciersbeheer
- Kleinere contracten in plaats van grote, monolithische systemen
- Multidisciplinaire teams met agile werkwijzen
- Focus op het aantrekken van diverse leveranciers, inclusief SME's
-
Gebruikersonderzoek en service design
- "Start with user needs" als fundamenteel richtlijn
- Regelmatige gebruikerstests en iteratie
- Data-gedreven besluitvorming
GDS richtlijnen en methoden
GDS hanteert bewezen design richtlijnen die directe toepassing hebben voor Nederlandse overheidsorganisaties:
- Start met gebruikersbehoeften: Begrijp werkelijke problemen voordat je oplossingen bouwt
- Doe minder: Focus op kernfunctionaliteit in plaats van "nice-to-have" features
- Ontwerp met data: Gebruik analytics en gebruikersonderzoek voor beslissingen
- Maak het toegankelijk: Zorg dat services werken voor iedereen
- Itereer en verbeter regelmatig: Lanceer snel en verbeter voortdurend
GDS heeft bewezen dat een gebruikersgerichte, agile aanpak leidt tot betere services tegen lagere kosten. Hun openbare documentatie en ervaring van meer dan een decennium digitale transformatie maken hen een uitstekende inspiratiebron voor Nederlandse overheidsorganisaties die hun digitale services willen verbeteren.
Toepassing in Nederlandse context
Bij het toepassen van GDS-inzichten in de Nederlandse context, overweeg het volgende:
- Europese samenwerking: Deel ervaringen en best practices binnen de EU
- Lokale wetgeving: Pas methodieken aan voor Nederlandse privacy- en toegankelijkheidswetten
- Gemeenschappelijke standaarden: Gebruik het GOV.UK Design System als inspiratie voor Nederlandse design patterns
- Kennisuitwisseling: Leer van GDS's openbare documentatie en blog
Gerelateerde hulpmiddelen
- Government Design Principles: Fundamentele richtlijnen voor overheidsservices
- Service Manual: Praktische gids voor het bouwen van digitale services
- Technology Code of Practice: Richtlijnen voor technologiekeuzes
- GDS Blog: Actuele inzichten en casestudies