Voorzie naast de documentatie in Respec ook in een EA bestand met daarin het CIM

VNG-Realisatie / API-Kennisbank

Afspraken, werkinstructies, tutorials, enz. voor de co-creatie en het beheer van API standaarden

https://vng-realisatie.github.io/API-Kennisbank/

6 stars 8 forks source link

Voorzie naast de documentatie in Respec ook in een EA bestand met daarin het CIM #143

Open melsk-r opened 3 months ago

melsk-r commented 3 months ago

Er wordt verzocht om bij de documentatie van een API standaard/specificatie naast het Respec document ook Enterprise Architect bestanden met het informatiemodel beschikbaar te stellen. XMI bestanden van het informatiemodel voldoen helaas niet omdat die niet in de EA Viewer geïmporteerd kunnen worden.

melsk-r commented 3 months ago

Mijn vraag is welke nadelen hieraan kleven. De vraag is dan of de voordelen opwegen tegen de nadelen. Hieronder de nadelen die ik zo vlug zie:

De bestanden kunnen een eigen leven gaan leiden;
Voordat we een EA bestand kunnen aanbieden moeten we de er in voorkomende modellen eerst ontkoppelen van het versiebeheer;
Het aanbieden van dit soort bestanden leidt mogelijk tot supportvragen op EA;
...

markbacker commented 3 months ago

Nu gebruiken we voor informatiemodellen GitHub alleen als publicatieplatform. Voor versiebeheer wordt gebruik gemaakt van subversion.

De zorgen over versies verdwijnen als voor het versiebeheer van de informatiemodellen git gebruikt (kan) worden. Er komen vast andere problemen voor terug, maar wellicht is dit oplosbaar?

Je kunt informeren hoe andere EA gebruikers dit oplossen. Ik denk dan vooral aan GGM, waar het informatiemodel in meerdere formaten op GitHub gedeeld wordt, ook het EA bronbestand (zie https://github.com/Gemeente-Delft/Gemeentelijk-Gegevensmodel)

hdksi commented 3 months ago

Versiebeheer van model meenemen in de repo van de standaardfamilie zou inderdaad het mooist zijn @markbacker, maar EA werkt niet (vanzelf) samen met Git. Mogelijk zijn er alternatieven, maar ik zou op basis van dit ene verzoek niet onze hele modelleringsworkflow overhoop willen halen.

Vanuit oogpunt van transparantie en faciliteren van hergebruik van lijkt het me in ieder geval een goed idee om modelbestanden in één of meer veelgebruikte formaten beschikbaar te stellen. Daarbij zou ik dan wel de opmerking opnemen dat we die delen op 'as is, where is' basis - dus zonder garantie of support. Daarnaast zou ik ervoor pleiten gepubliceerde niet-actuele versies actief offline te halen om te voorkomen dat oude versies (meer dan strikt noodzakelijke) verwarring opleveren.