Open CathyDingemanse opened 4 years ago
JohanBoer
commented
4 years ago Het doel van die descriptions lijkt mij om de consumer-developer snel van de plek te helpen. Volgens mij waren de features met name om provider-functionaliteit te beschrijven. Ik kan niet goed afwegen wat voor de developer belangrijker is. Korte descriptions met een duidelijke uitleg op een andere plek, of direct de uitleg beschikbaar, maar dan wel in een langere description.
JohanBoer
commented
4 years ago Melvin zoekt uit wat de beste optie is. Eventueel ook examples hierin betrekken.
MelvLee
commented
4 years ago Ik heb geprobeerd in een feature te beschrijven hoe 'kadastraal onroerende zaken zoeken' moet werken. Zie: https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/blob/docs/kadastraal-onroerende-zaken-zoeken/features/kadastraal-onroerende-zaken-zoeken.feature. Ik heb hierdoor igv één zoek pad gevonden die niet werkt zoals beschreven in de OAS, namelijk zoeken op adres kenmerken. Volgens de OAS is alleen postcode verplicht, maar zonder huisnummer krijg ik altijd een 404.
fsamwel
commented
4 years ago @MelvLee zeg je hiermee ook dat je liever de werking van de API voor gebruikers uitlegt in een feature (waarnaar je verwijst) dan in de API specificaties (yaml)?
MelvLee
commented
4 years ago Ik zou niet én de specificatie én alle documentatie in één yaml bestand proberen te stoppen. Ik denk dat een compacte description handig is als een soort reminder. Maar om complexe functionaliteit (zoals alle zoek mogelijkheden/combinaties) te snappen heb ik zeker uitgebreidere documentatie nodig
zodat de descriptions korter worden.
[beschrijf de impediment]
[assign aan ..., voeg label 'impediment' toe, kies bij 'projects' voor "organisatie en impediments"]