ReSpec

We maken standaarden met ReSpec. De inhoud van ReSpec documenten zit in Markdown bestanden die je met een text editor kunt bewerken. De bestanden worden in een GitHub repository beheerd. ReSpec

• zorgt voor een uniforme styling,
• onderhoudt referenties en verwijzingen naar andere documentatie,
• verzorgt de inhoudsopgave,
• zorgt voor links naar vorige en meest recente versies,
• heeft een integratie met Github issues.

Het volgende diagram beschrijft het proces voor het maken van een ReSpec publicatie:

Het proces bestaat uit een voortbrengingsproces waarin met het werkveld het document wordt gemaakt. Als uit dit proces een publiceerbare versie ontstaat wordt deze via het publicatieproces gepubliceerd.

Geonovum gebruikt de Logius ReSpec in een GitHub omgeving voor het beheer van de documenten.

Documentatie over ReSpec is te vonden - Er is een gedetailleerde gebruikershandleiding beschikbaar. - Er is ook een ontwikkelaarshandleiding te vinden. - Ook de template is een mooi startpunt.

Het voortbrengingsproces

• ReSpec documenten worden beheerd in een GitHub repository. Meestal zit er één ReSpec document in een repository.
• Maakt met git clone een lokaal kopie van repository waarin het ReSpec document zodat je het lokaal kunt bewerken. Een overzicht van alle GitHub repositories van Geonovum staat hier.
• Het lokale kopie bestaat uit een collectie bestanden. De tekstuele inhoud zit meestal in markdown (*md) bestanden. Deze kan je nu lokaal wijzingen
• Met git commit en git push kun je de lokale wijzingen naar de centrale werkversie overzetten.

Een ReSpec document publiceren op docs.geostandaarden.nl

Zie ReSpec publiceren

Een nieuw ReSpec document aanmaken

ReSpec documenten worden beheerd in een GitHub repository.

Gebruik de Geonovum ReSpec template om een nieuw document te maken; druk op 'Use this template'. Dit maakt een GitHub repository met een template document. Dit kun je meteen gaan wijzigen. Pas op alle plekken waar TODO staat het document aan.

Regel: kies een logische naam voor het repository.

Regel: Een github repository mag maar één ReSpec document bevatten.

Strategie multi-document repository opsplitsen

Aangezien de regel geldt dat een github repository maar één ReSpec document mag bevatten. is het nodig om de repository op te splitsen naar repositories met een enkel document. Het kan gewenst zijn om de verbinding tussen de 'ouder'-repository en alle 'kind'-repositories weer te geven via verwijzingen in README.md bij ouder/kind.

De nieuwe repositories dienen toegevoegd te worden aan een GitHub team, waarschijnlijk allen bij hetzelfde team als waartoe de 'ouder'-repository behoort.

Was-wordt representatie maken

Soms wordt er bij een publicatie een verschillijst (of was-wordt lijst) getoond waarin met kleuren de verschillen ten opzichte van de vorige versie zichtbaar worden gemaakt. Gebruik hiervoor de Online W3C HTML Diff service.