Welkom

• 1: Strategie van samenwerken
• 2: Werkomgeving
• 3: Contributie
• 4: Markdown
• 5: Samenwerking andere programma's
• 6: Template bouwblok

1 - Strategie van samenwerken

Van woningtekort en energietransitie tot armoede, schulden en zorg. Om maatschappelijke vraagstukken aan te pakken, is data binnen de overheid onmisbaar. Voor beleid, uitvoering, toezicht en verantwoording. De Interbestuurlijke Datastrategie (IBDS) is opgezet om de kansen van verantwoord datagebruik te benutten en om de knelpunten aan te pakken. Wat mag? Wat kan? Wat helpt? Wat inspireert?

De IBDS is het resultaat van nauwe samenwerking tussen departementen, uitvoeringsorganisaties en koepels van gemeenten, provincies en waterschappen. De IBDS is op 18 november 2021 naar de Tweede Kamer verzonden. Het streeft naar de verantwoorde inzet van data voor maatschappelijke opgaven en zet een ambitieuze stip op de horizon. Daarmee past het bij de doelen van het programma Werk aan Uitvoering (WaU) en de werkagenda Waardengedreven Digitaliseren.

Om de ambities uit de IBDS te realiseren, is in 2022 gestart met het programma Realisatie IBDS. In 2023 is interbestuurlijk de Meerjarenaanpak opgesteld.

Aanpak

De IBDS werkt vanuit de praktijk. Het programma jaagt de ontwikkelingen aan, vanuit verbinding en samenwerking, en door kennis en ervaringen met elkaar delen. Hiervoor brengt het programma over ketens heen partijen bij elkaar, die samen werken aan een vraagstuk. Dat is ook nodig om als overheid echt goed met data te kunnen werken. Bij vraagstukken rondom het woningtekort of de energietransitie zitten de databronnen immers nooit bij één partij.

Realisatie IBDS neemt hier het initiatief door strategie van samenwerken. Wij werken open en zijn toegankelijk voor samenwerking en hulp. Wij faciliteren het gesprek, de verbinding, de samenwerking. Tegelijk moeten er keuzes gemaakt worden. Wij ondersteunen de discussies en het proces om te komen tot echte interbestuurlijke besluiten.

Uitwerking

Het strategie van samenwerken werken wij concreet uit in een aantal punten.

Wij werken actief open

Om te kunnen samenwerken is het noodzakelijk dat we transparant zijn, open zijn in wat we doen. Onze intenties, onze ideeën, onze ontwikkeling is open te volgen. Al onze documenten zijn in principe openbaar. (Uitzonderingen betreffen vooral interne bedrijfsvoering en bescherming van persoonsgegevens)

Daarnaast hebben wij een open houding en zijn wij toegankelijk. Wij zijn bereikbaar, aanspreekbaar, zichtbaar.

Wij werken community gedreven

Samenwerking over organisatiegrenzen heen is per definitie een vorm van werkgroepen, samenwerkingsverbanden, van communities. Wij werken actief aan de ontwikkeling van communities. We bouwen een eigen netwerk van communities door bestaande communities te verbinden en te ondersteunen.

Communities zijn gebaat bij goede communicatie. We werken actief aan goede ondersteuning van communicatie. Dit richt zich op vier onderdelen:

• Publicatie en ’landingsplaats’; dit is het startpunt voor alle communicatie
• Documenten, publiek en met goed versiebeheer ondersteunt
• Chat en directe communicatie kanalen
• Issue tracking, beheer van vragen en opvolging

Wij verbinden

Er is al heel veel beschikbaar. Er zijn programma’s, ontwikkelingen, doorontwikkelingen die al jaren onderweg zijn. Er zijn ‘good practices’ die zich al bewezen hebben. Wij maken graag gebruik van wat er al is, van wat zich al bewezen heeft.

Wij faciliteren daarom inzicht en overzicht in programma’s, ontwikkelingen van organisaties en verbinden actief op thema’s. Uiteraard beperken we ons hierin voor zaken die gericht zijn op en verband houden met het federatief datastelsel.

Open werken is in de open source ‘wereld’ al lang in ontwikkeling. Daar is werken in communities ook bekend en beproefd. Voor het actief open werken kunnen we daar van leren en overnemen wat daar goed werkt.

Wij nemen faciliterend initiatief

Wij nemen initiatief op bovenstaande zaken. Op deze manier faciliteren wij het gesprek, discussies en onderwerpen. Door het nemen van het initiatief hierin laten we leiderschap zien. Wij zijn gericht op het ontwikkelen van vertrouwen van en in de communities.

Het vertrouwen is belangrijk en van belang. Uiteindelijk staan we voor moeilijke keuzes. Als maatschappij en overheden gaan we veranderingen door moeten maken. Dat vraagt om het nemen van besluiten. Wij zijn faciliterend in het gesprek en de discussies en tegelijk gericht op het nemen van besluiten. Wij zijn daarom actief gericht op het tot besluiten brengen van discussies. Ten overvloede, dit willen in en met vertrouwen doen in het netwerk van communities, waarin belangen juist en secuur worden afgewogen. Hierin komt het Waardengedreven Digitaliseren tot uiting.

Links

• doc Raamwerk (voor ontwikkeling in samenwerking)
• doc Werkomgeving
• DR 00001 Basisstructuur
• DR 00003 Werkomgeving voor ontwikkeling

Ter inspiratie links over diendend leiderschap:

• Talentontwikkeling | Betere teamprestaties dankzij dienend leiderschap
• pw. | Wat is dienend leiderschap?
• Psychologie van Succes | De essentie van Dienend Leiderschap (met Inge Nuijten)

2 - Werkomgeving

Zoals beschreven in onze strategie van samenwerken werken wij open en community gedreven. Daarom faciliteren wij in een omgeving waarin open samenwerking in kan floreren. Die omgeving beslaat een aantal aspecten van communicatie van een community:

• Publicatie en landingsplaats
• Ontwikkeling van documenten (en code)
• Interactie, zoals chat en online communicatie
• Issue tracking; het volgen en communicatie over issues

Community

Een community is … voor ons elke groepsvorm. Mensen werken samen in enige vorm, vanuit enig gedeelde achtergrond of driver. Graag willen we communities ondersteunen, verwelkomen en zo de samenwerking bevorderen en faciliteren. En toch … zijn er dan spelregels nodig.

We laten ons inspireren door ‘open source communities’. Hierin is het gewoon om een kern van ‘core committers’ te hebben. Zij zijn de ‘guardians’, de beschermers, de hoeders van de community. Zo geldt dat ook voor de community rondom het federatief datastelsel. In beginsel is het ‘FDS Team’ deze groep van ‘core committers’. Bij de groei van de community en de ontwikkeling van het federatief datastelsel zijn veranderingen zeker mogelijk. Maar we moeten ergens beginnen.

Om de kern bevindt zich een grotere groep van ‘contributors’. Dit zijn mensen die vanuit verschillende expertise, achtergronden, teams en whatever bijdragen doen aan ‘het open source project’; in dit geval het federatief datastelsel. Dit is iedereen die een bijdrage in enige vorm doet. Dat kan door opmerkingen te maken, heuse bijdragen in Merge Requests (of Pull Requests) aan te leveren, vragen te stellen, antwoorden te geven, actief betrokken in discussies en communicatie. Dit is open voor iedereen om in te stappen. Ook hiervoor gelden er regels om ordelijk en goed met elkaar om te gaan en inclusief te zijn. Zie hiervoor onze Contribution Guidelines.

Iedereen die meeleest, volgt en gebruik maakt van de kennis en functionaliteiten van het federatief datastelsel, kan gezien worden als ‘gebruiker’. Dit is de grote groep mensen, geïnteresseerden en passief betrokken mensen. Uiteindelijk doen we het daarvoor. Als we van toegevoegde waarde kunnen zijn voor onze gebruikers, dan gaat het goed. Gebruikers is hier wel een enigszins ongelukkige term, want uiteindelijk gaat het natuurlijk om het ondersteunen van maatschappelijke vraagstukken en het delen van de data die daarvoor nodig is. Gebruikers zijn dan de mensen die hierbij helpen, gebruik van maken of in enige vorm geraakt worden door wat er met het federatief datastelsel mogelijk wordt of daar ontwikkeld wordt.

Publicatie en ontwikkeling documenten

Voor de publicatie en landingsplaats voor iedereen, zowel intern als extern, gebruiken wij Pleio: realisatieibds.nl. Dit is de formele publicatie en communicatie kanaal.

Toch is alleen deze Pleio site onvoldoende. Of beter gezegd: het versiebeheer en samenwerken is onvoldoende. Daarvoor kiezen we graag voor best of breed tools. Aangezien Git een superieur en de facto standaard versiebeheersysteem is, kiezen we voor een open omgeving om daarmee te kunnen werken. GitLab is hier de ’tool of choice’. Dat betekent dat de ontwikkeling en samenwerking op documenten in Git gebeurt. Daarvoor is een eenvoudig formaat nodig waarin de inhoud (content) van de documenten wordt ontwikkeld en van waaruit nette publicatie site gegenereerd kan worden. Daarom passen we daar Markdown toe. Dit is een eenvoudig formaat van tekst in tekstbestanden, wat voor Git ideaal is, en ook machine-leesbaar is. De in de tekst toegevoegde opmaaktekens worden omgezet naar visuele opmaak bij het produceren van een website. Dezelfde tekst (bron) kan gebruikt worden om ook andere formaten zoals PDF te produceren.

Git

Wat is Git? Git is een versiebeheersysteem (Version Control System). Maar wat is dat precies?

Stel: Je werkt aan een set van documenten. Deze documenten heb je in een mapje (directory, folder) op je laptop staan. Op een gegeven moment heb je een versie die klopt. De samenhang is goed. De verwijzingen onderling zijn goed. Je wilt die versie wel even bewaren voordat je er in verder gaat werken. Daarom maak je een kopie van de collectie van bestanden. Het gemakkelijkste daarvoor is een kopie van de map te maken waar de hele collectie van bestanden in zit. Vervolgens werk je verder en af en toe vergelijk je de nieuwe versie met de vorige versie. Of zelfs vorige versies …

Dit is precies de functionaliteit die Git biedt!! Zo’n kopie bewaren heet een git commit. Je ‘commit’ al je wijzigingen die je op dat moment hebt opgespaard. Vervolgens biedt Git je vele mogelijkheden om te vergelijken (diff), samen te voegen (merge), met verschillende kopieën naast elkaar door te werken (branch), etc, etc. Er zijn zelfs hele workflows omheen ontstaan, die helpen om bijdragen op een goede manier te reviewen, te accepteren en samen te voegen in de volgende versie van de verzameling documenten (of code). Dat komt omdat Git zeer uitgebreid is in het werken met branches. Zo’n branch is een parallelle kopie waarin wijzigingen als commits kunnen worden gedaan en bewaard.

Een branching workflow met Git ziet er dan als volgt uit:

GitLab

Een verzameling bestanden, documenten (of broncode) wordt in Git beheerd in een Git repository, ook wel afgekort naar Git repo. Git biedt uitgebreide mogelijkheden om repositories decentraal te beheren en om vervolgens wijzigingen (commits) uit te wisselen. Er is technisch geen centrale opslag of server nodig … maar voor de samenwerking met mensen is dat wél nodig 😄 Dit wordt vaak de Git hub genoemd; de hub tussen alle decentraal beheerde repo’s (repositories). Wij kiezen voor GitLab als de ‘Git hub’ / centrale Git server. (Bekend alternatief is GitHub en aangezien men hier wellicht mee bekend is, wordt in dit artikel bij sommige onderdelen de GitHub terminologie ook benoemd.)

GitLab (en vergelijkbare producten als GitHub) bieden allerlei ondersteuning via het web. Zoals gezegd heeft Git sublieme mogelijkheden om in branches parallel te kunnen werken. Parallel betekent in deze dat mensen parallel kunnen werken, maar ook dat versies of documenten met verschillende aandachtsgebieden parallel kunnen worden ontwikkeld. GitLab biedt dan vervolgens ondersteuning in het review proces en de merge van zo’n parallelle branch in het ‘hoofd product’, de main branch. Dit heet (in GitLab) een Merge Request (in GitHub: Pull Request). Zo’n Merge Request geeft een goed inzicht in wat er veranderd is, wat er toegevoegd wordt, wat er verwijderd wordt. Het biedt ook mogelijkheden om commentaar te geven in het review proces. En dit alles inzichtelijk en gedetailleerd. Het niveau van detail kan zelfs wel overweldigend ervaren worden 😉

Sources

Markdown

Markdown is een veelgebruikte standaard en misschien wel de facto standaard voor de ontwikkeling van documenten. Aangezien wij deze breed willen inzetten, is de beschrijving en toelichting op de opmaak opgenomen in onze help: Docs / Markdown.

Links

• doc Strategie van samenwerken
• doc Raamwerk voor ontwikkeling in samenwerking
• DR 00001 Basisstructuur
• DR 00003 Werkomgeving voor ontwikkeling
• Docs / Contributie
• Docs / Markdown

3 - Contributie

Bovenstaande links zijn goede startpunten om dit platform te verkennen!

1. Welkom: Klik hier op en lees wat het doel is van dit platform en hoe we willen samenwerken.
2. Werkomgeving: Klik hier op en lees wat voor community we willen zijn en hoe we met elkaar kennis ontwikkelen, daarnaast leggen we je uit wat Git is
3. Mattermost: Klik hier op en je komt direct in onze chatomgeving van het FDS terecht. Hier kun je alle vragen stellen!
4. CMS: Klik hier op en je komt direct in de CMS omgeving waar je aan de slag kan.
5. Sources: Klik hier op en je komt direct in de Git omgeving waar je aan de slag kan.

Hoe kan ik contributies leveren?

Contributies zijn zeer welkom! Er zijn verschillende vormen van bijdragen en betrokkenheid. Om te beginnen is het mogelijk om via chat vragen te stellen en/of mee te discussiëren. Dat kan via Mattermost. Daarnaast is het mogelijk om issues aan te maken die gerelateerd zijn aan de content van deze site. Dat kan in GitLab. Daar wordt ook de bron van de content mbv versiebeheer ontwikkeld en dat is gelijk de mooiste manier van bijdragen: een merge request met daarin je voorstel voor wijzigingen en/of bijdragen! Hopelijk bieden onderstaande hoofdstukjes voldoende houvast om bijdragen te kunnen doen en anders horen we graag hoe we dat beter kunnen maken 😃

Ben je nog niet bekend met Git of wil je een gemakkelijke manier om vandaag al kennis en expertise toevoegen? Dat kan! Wij hebben een alternatieve mogelijkheid ontwikkeld, die het direct voor een ieder toegankelijk maakt. Gebruik hiervoor ons CMS (Content Management Systeem).

CMS

Voor het werken in het CMS (Content Management Systeem) heb je een GitLab account nodig. Na inloggen kun je dan direct aan slag!

Vervolgens zijn er twee manieren om aan de slag te gaan:

1. Navigeer naar het bouwblok waar je aan wilt bijdragen, bijvoorbeeld de deelnemerslijst. Heb je hier input voor en wil je die toevoegen?
   1. Klik aan de rechterkant op ‘ Bewerk (deze pagina) met CMS’. Je komt dan direct op de pagina terecht waar je diverse invulvelden ziet.
   2. Vul de tekst die je wilt toevoegen aan bij het blok aan de linkerkant.
   3. Vergeet niet op te slaan! Bovenin staan knoppen om je te begeleiden bij het opslaan en doorlopen van de workflow om je wijzigingen geaccepteerd te krijgen.
2. Ga direct naar CMS en krijgt een overzicht van alle pagina’s.
   1. Klik hier op het onderwerp waar je input wilt geven.
   2. Hier kan je meteen alles invullen. De legenda eronder begeleidt je bij de stappen.
   3. Vergeet niet op te slaan! Bovenin staan knoppen om je te begeleiden bij het opslaan en doorlopen van de workflow om je wijzigingen geaccepteerd te krijgen’
3. Wil je een geheel nieuw artikel/informatiepagina toevoegen?
   1. Ga naar CMS
   2. Klik op ’nieuwe content’ en maak helemaal een nieuwe pagina aan!
   3. Vergeet je niet op te slaan?

Kom je er niet uit? Stuur via Mattermost een berichtje en we kijken met je mee.

Mattermost

Voor chat functionaliteit maken we gebruik van Mattermost. We liften mee op de ontwikkelingen van Digilab en gebruik dan ook hun Mattermost omgeving. In Mattermost is een ‘Federatief Datastelsel’ ’team’ (Mattermost jargon) waar alle federatief datastelsel vragen en discussies plaatsvinden. Deze is te vinden op: digilab.overheid.nl/chat/fds.

Het kanaal ~algemeen is het startpunt van alle vragen en discussies!

Git

Voor versiebeheer maken we gebruik van Git. Dit is hét versiebeheersysteem van dit moment … en al voor jaren!

Meer informatie over het werken met Git vind je op developer.overheid.nl
(voor dit moment is deze info ook hieronder te vinden)

GitLab

We hebben gekozen voor GitLab als platform om mee te werken. De content van deze website is te vinden op: gitlab.com/datastelsel.nl/federatief/website

Issues

GitLab ondersteunt issues. ‘Issues’ is het jargon voor ‘alles wat maar een taakje zou kunnen zijn’. Het duidt dus niet alleen maar op problemen, maar op vragen, verzoeken, uitzoekwerk, etc, etc.

In het issue board kun je nieuwe issues aanmaken met je wensen, vragen en opmerkingen. Maak deze aan in de kolom ‘Open’ door op het te klikken.

Merge request

Heuse bijdragen aan de content van deze site kan met behulp van een ‘merge request’. Daarvoor is het wel noodzakelijk om begrip te hebben van hoe Git werkt en hoe je een merge request kunt aanmaken.

Een Git repository bevat een collectie bestanden die, in dit geval, de content vormen van deze site. De ‘Core Committers’ van deze repo zijn (op dit moment) van het team IBDS/FDS. Je kunt in de groep van ‘Contributors’ komen, door een fork te maken onder je eigen naam of organisatie (in GitLab). Een fork is een apart soort branch onder een andere organisatie dan de originele repository. Daar ben jij dan ‘Core Committer’ van en kun je je wijzigingen doen dmv Git commits. Vervolgens kun je een ‘Merge Request’ aanmaken terug naar de originele repository. Deze wordt dan zichtbaar bij de ‘Core Committers’ van federatief.datastelsel.nl en zij kunnen deze accepteren. Accepteren betekent dat de wijzigingen worden opgenomen in de repository van deze website. Daarop volgt een update van de website met de nieuwe content. Voorafgaande aan het accepteren wordt er eerst een review gedaan door de ‘Core Committers’ en kan eventueel commentaar en discussie volgen over de bijdragen.

Als je je bijdrage maken hebt afgerond, kun je via je browser navigeren naar de repository in GitLab. Afhankelijk van waar je branch staat, bijvoorbeeld in je fork, geeft GitLab je al een hint om een Merge Request te maken:

Een andere manier is om je branch te bekijken en te vergelijken (‘compare’) met het origineel (of de main branch). Daar biedt GitLab je vervolgens ook de mogelijkheid om een Merge Request aan te maken:

Online werken

Om online contributies te doen is het mogelijk om de ‘Web IDE’ te openen. IDE staat voor Integrated Development Environment. Dat klinkt technisch … en dat is het wellicht ook wel een beetje. Tegelijk hoeft je niet alle mogelijkheden te gebruiken en is het ook ‘gewoon een editor’ 😉

Om de ‘Web IDE’ te openen navigeer je eerst naar de repository in GitLab:

Vervolgens klik je op Edit > Web IDE

Vervolgens wordt er een online versie van VSCode geopend waarin wijzigingen gedaan kunnen worden. Volg daarna de instructie van bijdrage maken.

Offline werken

Om offline te kunnen werken en niet per se een internetverbinding nodig te hebben, is het mogelijk om op je computer, lokaal, een kopie van de repository te maken. Daarvoor maken we ook gebruik van Git functionaliteiten. Eigenlijk lijkt dat op het maken van een fork (zie bovenstaande) maar dan maak je een lokale kopie. Dat heet (Git jargon) een clone.

Installatie

Voorwaarden om lokaal op je eigen computer te kunnen werken, is beschikbaarheid van een aantal geïnstalleerde tools:

1. VSCode (Visual Studio Code - Microsoft)

2. Git-scm (Source Code Management - open source)

   (kies bij de installatie voor alle ‘defaults’ behalve default editor; hier kies je voor Use Visual Studio Code as Git's Default Editor)

Configuratie

Er is enige configuratie nodig om optimaal te kunnen werken. Volg deze stappen:

1. Open VSCode (na installatie van Git-scm)

2. Open een terminal om Git te configureren (klinkt eng, maar valt reuze mee 😉 - zie ook GitLab Basics documentatie)

3. Type het volgende commando in (copy-paste mag, maar pas aan naar je eigen gegevens)

   git config --global user.name "Mona Lisa"

4. Type het volgende commando in (copy-paste mag, maar pas aan naar je eigen gegevens)

   git config --global user.email "mona.lisa@mail.com"

5. Sluit de terminal af met het commando:

   exit

Clone

We zijn nu klaar om een lokale kopie te kunnen maken. GitLab biedt daarvoor een eenvoudige optie:

1. Navigeer naar de repository in GitLab: gitlab.com/datastelsel.nl/federatief/website

2. Klik op Code > Visual Studio Code (HTTPS)

   

3. VSCode wordt geopend en je krijgt de vraag waar de lokale kopie op je computer opgeslagen moet worden. Hier dien je een map op te geven waarin Git voor jou een map aanmaakt die heet website. Dat komt omdat de repository (het laatste stukje) zo heet (Git default; is aanpaspaar … maar vraag extra Git kennis)

   Gebruikelijk is een map waarin alle lokale repositories staan, bijvoorbeeld: C:\repos

   NOTE Een bekend probleem is lange bestandsnamen. Kies daarom een map die niet al heel erg diep genest is en een moeilijke naam heeft. Dat zorgt nog wel eens voor onverklaarbare problemen.

4. Nadat je de map gekozen hebt waarin Git voor jou een kopie maakt van de repository, de ‘clone’, opent VSCode deze direct en kun je aan de slag om je bijdragen te maken. Volg daarin dezelfde werkwijze als het online werken: bijdrage maken.

Bijdrage maken

Voordat je begint met het maken van wijzigingen, is het van belang om een branch te maken. Dit is Git functionaliteit om zonder een ander tot last te zijn en om wijzigingen goed te kunnen beheren, op een ‘kopie’ te werken. Een branch biedt de mogelijkheid om wijzigingen te maken in meerdere bestanden en met meerdere commits, deze te verzamelen en als geheel te reviewen en te accepteren.

In VSCode zie je continue in welke branch je zit, links onderaan in je scherm. Door daarop te klikken kun je kiezen om een andere branch te selecteren en/of om een nieuwe branch te maken. Het is raadzaam om te beginnen met een nieuwe branch voordat je wijzigingen maakt.

Git kent vele mogelijkheden en manieren om versiebeheer toe te passen en het is bijna moeilijk om wijzigingen kwijt te raken. Tegelijk kan dat ook bijzonder complex worden. Het is daarom raadzaam om gestructureerd en methodisch te werken. Voor problemen met Git en/of wijzigingen kun je altijd hulp vragen in Mattermost

Om een bijdrage te maken is het nodig om te weten waar je een bijdrage wilt gaan maken. Je wilt een nieuw onderwerp toevoegen of een wijzigingsvoorstel maken op bestaande pagina’s. Vrijwel alle inhoudelijke wijzigingen en bijdragen bevinden zich in de map content. Dat is een goed begin om te gaan zoeken naar de pagina waarin je een bijdrage zou willen maken.

Navigeer aan de linkerkant in VSCode door de ‘Explorer’ om de juiste pagina te vinden. Door daarop te klikken, wordt de pagina geopend. Dit is Markdown. Gebruik Markdown opmaak symbolen om je wijzigingen te maken.

Plaatjes zijn eenvoudig toe te voegen door deze in een submapje images te kopiëren of plakken. Het is ook mogelijk om op de plek waar je een plaatje wilt invoegen in de Markdown, gewoon een plaatje te plakken van het klembord (Ctrl+v). VSCode (zowel online als offline) vertaalt dit naar een image.png en voegt passende Markdown opmaak toe om het plaatje weer te geven.

VSCode biedt de mogelijkheid om een preview van de Markdown pagina direct weer te geven binnen VSCode. Er zijn meerdere manieren om deze weer te geven. Kies één van de volgende opties:

• Klik op de ‘preview button’ rechts bovenaan
• Gebruik de shortcut Ctrl + k v (dus eerst Ctrl + k en daarna een ’losse’ v)
• Open het ‘Command Palette’ van VSCode met de shortcut Ctrl + Shift + P en type het gewenste command (bijv. begin met typen van preview en selecteer Markdown: Open Preview to the side)

Nadat je alle gewenste wijzigingen hebt gemaakt, dat kan in meerdere bestanden zijn, dien je al je wijzigingen te bewaren met een ‘Git commit’ (Git jargon). Een commit wordt in bovenstaande plaatjes aangeduid met een bolletje. Het bevat een verzameling van wijzigingen in één of meerdere bestanden. Daarvoor wil je eerst zien wat je wijzigingen zijn en deze zelf reviewen. VSCode maakt dat gemakkelijk zichtbaar in het ‘Source Control’ window:

1. Selecteer Source Control (of gebruik shortcut Ctrl + Shift + G)

2. Hier zie je een overzicht van alle gewijzigde bestanden. Tijd voor een persoonlijke review!

   • Is dit wat je verwacht?
   • Je kunt elk bestand aanklikken om te zien wat je wijzigingen zijn
   • Maak eventueel meer wijzigingen om te komen tot je gewenste resultaat

3. Het is gebruikelijk en voor de traceerbaarheid prettig om enig commentaar te maken bij je verzameling wijzigingen, oftewel je ‘commit message’

   • Beschrijf in ’t kort (bij voorkeur binnen 50 karakters) waarom je deze wijzigingen hebt gemaakt

   • Eventueel kun je een korte zin gebruiken en vervolgens met enter uitgebreidere commentaren en opmerkingen maken

     NOTE Ook hier is Markdown opmaak te gebruiken

4. [optioneel] Git en VSCode ondersteunen dat je wijzigingen in verschillende commits doet. Daarvoor kun je in het lijstje van bestanden kiezen welke bestanden je mee wilt nemen in je commit. Klik daarvoor op de + van elk bestand dat je mee wilt nemen.

   NOTE Het is mogelijk om deze stap over te slaan. VSCode vraagt dan of alle gewijzigde bestanden meegenomen moeten worden in deze commit. Vaak is dat het geval en wordt deze stap dus overgeslagen. Gemak dient de mens 😄

5. Commit je wijzigingen door op de Commit knop te klikken

6. [extra voor offline werken!] In het geval dat je offline werkt, heb je nu een lokale branch gemaakt … maar deze is nog niet beschikbaar of bijgewerkt in GitLab. Daarvoor dien je je lokale repository (je clone dus) te synchroniseren met de online repository. In VSCode heet dat Synchonize maar wat er in werkelijkheid gebeurt, zijn twee stappen: een git pull en git push wat resp. de Git commando’s zijn voor het ophalen van wijzigingen en uploaden (wegduwen) van wijzigingen. In deze zijn de wijzigingen ‘de commits’.

Nadat je wijzigingen in een commit zijn vastgelegd én je commits zijn beschikbaar in GitLab, dan is het mogelijk om een Merge Request te maken 💪

4 - Markdown

Markdown is een lichtgewicht opmaaktaal op basis van platte tekst die zodanig ontworpen is dat het gemakkelijk valt te converteren naar HTML en andere formaten met een applicatie met dezelfde naam. Markdown wordt vaak gebruikt voor de opmaak van projectdocumentatie, eenvoudige CMS-systemen en berichten in online fora. - bron: Wikipedia

Markdown is platte tekst en daardoor ook goed machine-leesbaar. Dat heeft voordelen om meerdere formaten te produceren van dezelfde content. De opmaak wordt door ‘speciale opmaaktaal’ opgegeven in de tekst. In het genereren van een website of PDF worden die opmaak ‘codes’ omgezet in de juiste opmaak.

Doordat Markdown een open standaard is, zijn er vele editors en tools die kunnen ondersteunen bij het werken met Markdown. In alle gevallen is het handig om een klein beetje van de opmaaktaal te leren. Hiervoor zijn vele ‘Markdown cheat sheets’ te vinden … en hieronder staat onze eigen 😄

Waarom eigenlijk Markdown? Kijk daarvoor in onze blogs over strategie van samenwerken en onze werkomgeving.

Basic Syntax

Element	Markdown Syntax	Voorbeeld*
Heading	# H1 ## H2 ### H3	-
Bold	**bold**	bold
Italic	*italic* _italic_	italic
Blockquote	> blockquote	-
Ordered list	1. item 1 2. item 2 3. item 3 (alleen 1. mag ook; wordt automatisch genummerd ;)	1. item 1 2. item 2 3. item 3
Unordered list	- item 1 - item 2 - item 3	- item 1 - item 2 - item 3
Code	`code`	code
Link	[label](https://datastelsel.nl)	label
Image	
Horizontal rule	---	-

* Mits mogelijk om weer te geven in een tabel

5 - Samenwerking andere programma's

Hieronder maken we een begin met het beschrijven van andere overheidsprogramma’s waar wij mee samenwerken. Deze pagina zullen we met de tijd aanvullen en verscherpen op basis van de laatste inzichten.

Kennisplatform API’s en R-FDS

Doel: Het Kennisplatform API’s is opgericht door Geonovum in samenwerking met het Bureau Forum Standaardisatie, Kamer van Koophandel, VNG Realisatie, Logius en het Kadaster. Het doel van het platform is samen te werken aan strategische en tactische vraagstukken rond het ontwikkelen van API’s door de overheid . Dit resulteert in gedeelde kennis, afstemming, afspraken en standaarden.

Raakvlakken: Het FDS ziet het ontsluiten van data middels API’s als een belangrijk middel om vertrouwd data te delen in het stelsel en richt zich onder andere op uitwisselstandaarden die aansluiten op het inzetten van API’s maar minder op de spelregels rondom API’s zelf. Daar richt het Kennisplatform zich op. Het FDS werkt nauw samen met het Kennisplatform zodat beiden zich in lijn met elkaar blijven ontwikkelen.

Samenwerking: Kennisplatform API’s en FDS hebben momenteel gesprekken lopen om de samenwerking verder te concretiseren. Samen met Digilab en Developer Overheid is er al bepaald welke doelgroepen elk programma heeft en hoe we elkaar kunnen ondersteunen in het informeren van die doelgroepen via alle kanalen.

Neem vooral een kijkje op de website van Kennisplatform API’s

Developer.Overheid.NL en R-FDS

Doel: Developer.overheid.nl biedt een platform voor ontwikkelaars die voor of met de overheid werken. Het platform biedt toegang tot hoogwaardige API’s en Open Source repositories waarover inzicht gegeven wordt in een aantal kwaliteitskenmerken met behulp van testtools. De community faciliteert de uitwisseling van kennis en stimuleert de samenwerking tussen overheidsinstanties.

Raakvlakken: Het FDS heeft meerdere dimensies en een daarvan is de technische interoperabiliteit welke ondersteund wordt door het kiezen van uitwisselingsstandaarden. Binnen het FDS is niet veel ontwikkelkennis beschikbaar omdat er gekozen is om het ontwikkelen van standaarden buiten de FDS scope te plaatsen. Tegelijk is die ontwikkelkennis wel belangrijk om ook als FDS bepaalde puzzels te onderzoeken en keuzes te maken rondom de uitwisselingsstandaarden. Hier raken het FDS en het platform elkaar: ontwikkelkennis. Het platform biedt ruimte voor datasets (API’s) om zichtbaar te zijn voor de ontwikkelaars zodat deze best practices kunnen delen, vragen aan elkaar en de dataset eigenaar te kunnen stellen en indien wenselijk feedback ter verbetering kunnen geven.

Samenwerking: De technische keuzes die door het FDS en haar stakeholders gemaakt worden, worden op het platform gepubliceerd. Hierdoor bereikt het FDS een grote bron aan ontwikkelkennis waaruit enerzijds feedback gegeven wordt en FDS haar richting kan aanscherpen. Anderzijds geeft het FDS richting aan de ontwikkelaars zodat deze geholpen worden in het maken van eigen keuzes.

Neem vooral een kijkje op de website van Developer Overheid

6 - Template bouwblok

Beschrijving

Architectuurlagen

Grondslagenlaag

Hier vind je wetten en drivers.

Componenttypen die we hier verwachten:

• Doel/Driver
• Principe
• Requirement
• Afspraak/Standaard (Wet/Overeenkomst)

Organisatorische laag

De organisatorische componenten vind je hier.

Componenttypen die we hier verwachten:

• (Actor)
• Rol
• Functie
• Service
• Afspraak/Standaard
• (Contract)

Informatielaag

Componenttypen die we hier verwachten:

• Metadata-object
• Metadata-object-relatie
• Afspraak/Standaard

Applicatielaag

Componenttypen die we hier verwachten:

• Functie (Technische stelselfuncties)
• Applicatieservice
• Afspraak/Standaard

Technologielaag

Componenttypen die we hier verwachten:

• Node
• Netwerk
• Afspraak/Standaard